OAuth 2.0
Flujo Authorization Code + PKCE para integraciones de apps de terceros.
Rekomi tiene un servidor de autorización OAuth 2.0 conforme al estándar en api.rekomi.com/connect/*. Añade un botón "Conectar con Rekomi" a tu app y tus usuarios delegan el acceso a su cuenta de Rekomi sin copiar y pegar ninguna clave de API.
OAuth 2.0 es preferible a las claves de API cuando:
- Estás creando una integración que se distribuye a varias marcas de Rekomi (no solo a tu propia organización).
- Quieres que el usuario elija su propio scope (read o read_write) al dar su consentimiento.
- Necesitas rotación de refresh tokens en lugar de claves estáticas de larga duración.
- Necesitas que tus tokens se puedan revocar desde el panel de Rekomi del usuario.
Si solo te integras con tu propia organización, las claves de API siguen siendo el camino más sencillo.
Qué incluye
| Especificación | Estado |
|---|---|
| Flujo Authorization Code + PKCE (S256) | Obligatorio |
| Refresh tokens con rotación y detección de reutilización | Sí |
| Revocación de tokens (RFC 7009) | Sí |
| Introspección de tokens (RFC 7662) | Sí |
| Tokens de referencia (opacos, guardados en base de datos, revocables) | Sí |
| Claim de emisor en la respuesta de autorización (RFC 9207) | Sí |
Se admiten tanto clientes públicos (apps solo de navegador) como confidenciales (apps del lado del servidor con un secreto guardado). PKCE es obligatorio para todos los clientes, sea cual sea su tipo.
Endpoints
| Endpoint | Método | Propósito |
|---|---|---|
https://api.rekomi.com/connect/authorize | GET / POST | Inicia el flujo de autorización. Redirige el navegador a la pantalla de consentimiento. |
https://api.rekomi.com/connect/token | POST | Cambia el código por tokens o rota un refresh token. |
https://api.rekomi.com/connect/revoke | POST | Revoca un access token o un refresh token (RFC 7009). |
https://api.rekomi.com/connect/introspect | POST | Valida un token y lee sus scopes, su sujeto y su caducidad (RFC 7662). |
Hay un único entorno (api.rekomi.com); Rekomi no tiene un emisor de staging aparte.
Registra tu cliente
Para registrar un cliente, escribe a support@rekomi.com con:
- El nombre visible de tu app (se muestra en la pantalla de consentimiento).
- La URL del logo de tu app (solo https).
- El tipo de cliente:
confidential(el servidor guarda un secreto) opublic(app de navegador). - Las redirect URIs: una o más URLs https a las que se devuelve al usuario tras el consentimiento. No se permiten comodines; se exige coincidencia exacta según la sección 3.1.2 de la RFC 6749.
- Los scopes solicitados:
read,read_writey/ooffline_access.
Recibes un client_id y (en los clientes confidenciales) un client_secret. El secreto en texto claro se muestra UNA SOLA VEZ; guárdalo al momento. Si lo pierdes, pide a soporte que lo rote.
El registro de clientes en autoservicio está en la hoja de ruta. Hasta entonces, el registro manual mantiene la pantalla de consentimiento libre de "apps" de baja calidad o spam de las que los usuarios tendrían que aprender a desconfiar.
Clientes propios (first-party)
Rekomi mantiene sus propios clientes OAuth registrados para las integraciones propias. El primero es Zapier (la pantalla de consentimiento muestra el nombre de app Zapier), la superficie de automatización sin código que permite a las marcas conectar Rekomi con más de 8,000 apps. Los usuarios finales lo conectan igual que cualquier app OAuth de terceros: hacen clic en Connect dentro de Zapier, llegan a la pantalla de consentimiento en app.rekomi.com/oauth/authorize, eligen una organización y hacen clic en Permitir. Del lado de la marca no hay nada que instalar ni configurar más allá de ese clic de consentimiento.
Si eres un usuario final que intenta conectar Zapier (y no un desarrollador creando su propio cliente OAuth), sáltate el resto de esta página y ve a la guía de integración con Zapier.
Scopes
Hoy hay tres scopes:
read: ver campañas, afiliados, conversiones, pagos y el perfil de la cuenta. Sin cambios.read_write: todo lo deread, más crear campañas, aprobar afiliados, generar cupones, emitir pagos y modificar la configuración de la cuenta.offline_access: pídelo junto conreadoread_writepara recibir un refresh token. Sin él, la respuesta de tokens solo contiene un access token.
Jerarquía: read_write satisface cualquier requisito de read. read NO satisface un requisito de read_write. Pide el scope más estrecho que tu integración necesite de verdad; los usuarios ven el conjunto de scopes solicitado en la pantalla de consentimiento y te recomendamos ofrecerles la opción de reducirlo aún más.
Solo un Propietario de la organización puede aprobar un permiso read_write; los miembros con roles inferiores pueden aprobar el acceso de solo lectura. Quien no es Propietario e intenta conceder read_write recibe un 403 insufficient_role.
El flujo
1. Envía al usuario al endpoint de autorización
GET https://api.rekomi.com/connect/authorize
?response_type=code
&client_id=YOUR_CLIENT_ID
&redirect_uri=https://yourapp.example.com/oauth/callback
&scope=read_write offline_access
&state=A_RANDOM_STRING_TO_VERIFY_LATER
&code_challenge=BASE64URL_S256_HASH_OF_VERIFIER
&code_challenge_method=S256code_challenge es el hash SHA-256 de un code_verifier aleatorio de entre 43 y 128 caracteres que generas tú, codificado después en base64url sin relleno. Guarda el verifier para el paso 3.
state es tu defensa contra CSRF; te lo devolvemos tal cual en el callback, y debes rechazar el callback si el valor no coincide con el que enviaste.
El navegador se redirige a la pantalla de consentimiento en app.rekomi.com/oauth/authorize. El usuario inicia sesión si no lo ha hecho ya; la pantalla de consentimiento muestra la organización a la que quedará vinculado el permiso (la que esté activa en ese momento), junto con la identidad de la app y los scopes solicitados. Para autorizar otra organización, el usuario cambia de organización en el panel y vuelve a empezar el flujo. Después hace clic en Permitir o Denegar.
2. Gestiona el callback
Tras el consentimiento, el usuario vuelve a:
https://yourapp.example.com/oauth/callback
?code=ONE_TIME_AUTHORIZATION_CODE
&state=A_RANDOM_STRING_TO_VERIFY_LATER
&iss=https://api.rekomi.comComprueba que state coincide con el que enviaste en el paso 1. Comprueba que iss es https://api.rekomi.com. Si cualquiera de las dos comprobaciones falla, aborta el flujo.
Si el usuario hizo clic en Denegar, recibes:
?error=access_denied
&state=A_RANDOM_STRING_TO_VERIFY_LATER3. Cambia el código por tokens
Haz un POST al endpoint de tokens antes de 60 segundos (los códigos caducan así de rápido):
POST /connect/token HTTP/1.1
Host: api.rekomi.com
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&code=ONE_TIME_AUTHORIZATION_CODE
&redirect_uri=https://yourapp.example.com/oauth/callback
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&code_verifier=THE_VERIFIER_FROM_STEP_1Respuesta:
{
"access_token": "an-opaque-reference-token-256-bits",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "another-opaque-reference-token",
"scope": "read_write"
}access_token es un token de referencia, NO un JWT. Es opaco. Guárdalo tal cual; no intentes decodificarlo.
4. Llama a la API de Rekomi
GET /api/v1/programs HTTP/1.1
Host: api.rekomi.com
Authorization: Bearer ACCESS_TOKEN_FROM_STEP_3El bearer autentica Y a la vez identifica la organización para la que el usuario dio su consentimiento. NO necesitas enviar una cabecera de organización aparte; la vinculación a la organización quedó fijada al dar el consentimiento y se aplica en cada petición.
Si el usuario revoca tu autorización desde app.rekomi.com/dashboard/settings/connected-apps, la siguiente llamada a la API devuelve 401 Unauthorized. Los intentos de refresh posteriores también devolverán 401. Antes de que se haya autorizado ninguna app, esa página muestra un estado vacío; en cuanto una integración se conecta, aparece ahí con un control para revocarla.

5. Renueva los tokens
Los access tokens caducan al cabo de una hora. Cuando recibas un 401, rota el refresh token:
POST /connect/token HTTP/1.1
Host: api.rekomi.com
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRETLa respuesta tiene la misma forma que en el paso 3. Importante: la respuesta incluye un refresh_token nuevo. El anterior se revoca al instante. Reutilizar un refresh token antiguo provoca que se revoque toda la familia de tokens (Rekomi sigue en esto el borrador OAuth 2.0 Security Best Current Practice). Tras la revocación de la familia, el usuario tiene que volver a conectar desde cero.
Los refresh tokens duran 30 días. Las integraciones activas (que renuevan dentro de la ventana de 30 días) en la práctica nunca necesitan que el usuario vuelva a autorizar.
6. Revocación
Si tu integración se desinstala, revoca los tokens que tengas:
POST /connect/revoke HTTP/1.1
Host: api.rekomi.com
Content-Type: application/x-www-form-urlencoded
token=ACCESS_OR_REFRESH_TOKEN
&token_type_hint=access_token
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRETUna respuesta 200 significa que el token ya no es válido. Según la RFC 7009, siempre recibes un 200 si las credenciales de tu cliente son válidas; el cuerpo de la respuesta va vacío.
Errores
| HTTP | error de OAuth | Significado |
|---|---|---|
| 400 | invalid_request | Falta un parámetro o está mal formado. |
| 400 | invalid_grant | El código caducó, ya se usó, o el refresh token está revocado. |
| 401 | invalid_client | client_id o client_secret incorrectos. |
| 401 | invalid_token | Access token revocado o caducado. Renueva y reintenta. |
| 400 | unsupported_grant_type | Hoy solo se admiten authorization_code y refresh_token. |
| 400 | unauthorized_client | El client_id no puede usar este tipo de grant. |
| 400 | invalid_scope | El scope solicitado no está registrado para este cliente. |
Duración de los tokens
| Token | Duración por defecto | Notas |
|---|---|---|
| Código de autorización | 60 segundos | De un solo uso. Cámbialo dentro de la ventana. |
| Access token | 1 hora | Token de referencia. Opaco. Revocable. |
| Refresh token | 30 días | Token de referencia. Rota en cada uso. |
Hoy las duraciones son las mismas para todos los clientes; contacta con soporte si tus requisitos de cumplimiento son distintos.
Requisitos de seguridad
- PKCE es obligatorio. Tanto para clientes públicos como confidenciales. Solo
code_challenge_method=S256. - Coincidencia exacta de redirect_uri. Sin comodines, sin puertos alternativos, sin otros esquemas.
- Tokens de referencia, no JWTs. Los tokens son ids opacos. No intentes decodificarlos.
- Rotación de refresh con revocación de la familia. Reutilizar un refresh token ya rotado revoca todos los tokens de la familia.
- La revocación es inmediata. Cuando un usuario hace clic en Revocar en su panel, la siguiente llamada a la API desde tu integración falla.
- Sin datos personales en las URLs. Los tokens NUNCA aparecen en query strings. El endpoint de autorización solo recibe los parámetros OAuth (que no son secretos).
- Secretos de cliente con hash en reposo. Nunca guardamos ni registramos el texto en claro.
- Vinculación a la organización al dar el consentimiento. Un token concedido en la organización A no puede leer la organización B aunque el mismo usuario sea miembro de ambas.
Ejemplo completo: cliente mínimo en Node
import crypto from "node:crypto";
import { URL, URLSearchParams } from "node:url";
const CLIENT_ID = process.env.REKOMI_CLIENT_ID;
const CLIENT_SECRET = process.env.REKOMI_CLIENT_SECRET;
const REDIRECT_URI = "https://yourapp.example.com/oauth/callback";
function base64url(buf) {
return Buffer.from(buf).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
}
// Step 1: build the authorize URL
export function buildAuthorizeUrl() {
const codeVerifier = base64url(crypto.randomBytes(64));
const codeChallenge = base64url(crypto.createHash("sha256").update(codeVerifier).digest());
const state = base64url(crypto.randomBytes(32));
const url = new URL("https://api.rekomi.com/connect/authorize");
url.searchParams.set("response_type", "code");
url.searchParams.set("client_id", CLIENT_ID);
url.searchParams.set("redirect_uri", REDIRECT_URI);
url.searchParams.set("scope", "read_write offline_access");
url.searchParams.set("state", state);
url.searchParams.set("code_challenge", codeChallenge);
url.searchParams.set("code_challenge_method", "S256");
// Stash codeVerifier + state in the user's session for the callback to read.
return { authorizeUrl: url.toString(), codeVerifier, state };
}
// Step 3: exchange code for tokens
export async function exchangeCode({ code, codeVerifier }) {
const body = new URLSearchParams({
grant_type: "authorization_code",
code,
redirect_uri: REDIRECT_URI,
client_id: CLIENT_ID,
client_secret: CLIENT_SECRET,
code_verifier: codeVerifier,
});
const res = await fetch("https://api.rekomi.com/connect/token", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body,
});
if (!res.ok) throw new Error(`Token exchange failed: ${res.status}`);
return res.json(); // { access_token, refresh_token, expires_in, scope, token_type }
}
// Step 5: refresh
export async function refresh({ refreshToken }) {
const body = new URLSearchParams({
grant_type: "refresh_token",
refresh_token: refreshToken,
client_id: CLIENT_ID,
client_secret: CLIENT_SECRET,
});
const res = await fetch("https://api.rekomi.com/connect/token", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body,
});
if (!res.ok) throw new Error(`Refresh failed: ${res.status}`);
return res.json();
}Auditoría y observabilidad
Cada consentimiento concedido, emisión de token, renovación, revocación desde el panel y reutilización de token detectada escribe una fila de auditoría visible para los propietarios de la organización en /dashboard/settings/audit-log.
Nombres de acción que verás:
oauth.consent.granted: el usuario hizo clic en Permitir en la pantalla de consentimiento.oauth.consent.revoked: el usuario hizo clic en Revocar en su página de Apps conectadas.oauth.token.issued: el código de autorización se cambió por tokens.oauth.token.refreshed: la rotación del refresh token se completó.oauth.token.reuse_detected: se reutilizó un refresh token ya rotado; se revocó toda la familia.
Comparativa con las claves de API
| Capacidad | Clave de API | OAuth 2.0 |
|---|---|---|
| Tiempo de configuración | Segundos | Minutos (registro del cliente) |
| Pensado para | Tu propia organización | Integraciones para varios clientes |
| Forma del token | Cadena estática rk_live_* | Token de referencia opaco |
| Renovación | Ninguna (larga duración) | Sí (rotación a 30 días) |
| Visible para el usuario en el panel | Configuración → Claves de API | Configuración → Apps conectadas |
| El usuario puede revocar por su cuenta | Solo el Propietario | Sí (en cualquier momento) |
| Elección del scope | Al crearla | Al dar el consentimiento |
| Atribución por usuario | No (de toda la organización) | Sí (el usuario de Clerk es el Subject) |
Elige claves de API para tu propia automatización interna. Elige OAuth 2.0 cuando distribuyas a otras marcas.
Autenticación
Claves de API Bearer, permisos, secretos de firma, rotación y revocación.
Seguimiento servidor a servidor
Ingesta de conversiones firmada con HMAC para cualquier pasarela de pago más allá de las conexiones nativas con Stripe, Paddle, Braintree, Shopify, Wix, BigCommerce, Lemon Squeezy, Chargebee, Polar, Recurly, Gumroad, Creem, Dodo Payments y Mollie.