Tokens

​

Renueva el access token

curl -s https://api.craqui.com/oauth/token \
  -u "$CRAQUI_CLIENT_ID:$CRAQUI_CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token="$CRAQUI_REFRESH_TOKEN"

{
  "access_token": "crq_oat_TU_ACCESS_TOKEN_NUEVO",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "crq_ort_TU_REFRESH_TOKEN_NUEVO",
  "scope": "business:read clients:read payments:read",
  "business_id": "biz_01jtm0r4w8a3b6c9d2e5f7g1hk"
}

​

El refresh token rota en cada uso

1. Guarda el refresh token nuevo antes de usar el access token nuevo, en la misma operación en tu base de datos. Si tu proceso se cae entre una cosa y la otra y te quedas con el refresh viejo, puedes perder la conexión (salvo dentro del margen de 60 segundos de abajo).
2. Un solo renovador por negocio. Si dos procesos de tu app renuevan a la vez el mismo refresh token, uno de los dos se queda con tokens que ya no sirven y, cuando presenta ese refresh, se trata como un robo y la conexión se corta (abajo). Serializa la renovación por business_id: un lock en tu base de datos, una cola, o un único proceso que renueva.
3. No guardes tokens viejos. Un refresh que ya usaste no te sirve para nada, salvo en el margen de abajo.

export async function refresh(businessId: string) {
  // Tu lock por negocio: nadie más renueva este refresh token mientras tanto.
  return withBusinessLock(businessId, async () => {
    const current = await loadConnection(businessId);
    const response = await oauth.refreshTokenGrantRequest(as, client, clientAuth, current.refreshToken);
    const tokens = await oauth.processRefreshTokenResponse(as, client, response);
    // El refresh nuevo se guarda antes de usar el access nuevo.
    await saveConnection({
      businessId,
      accessToken: tokens.access_token,
      accessExpiresAt: Date.now() + (tokens.expires_in ?? 3600) * 1000,
      refreshToken: tokens.refresh_token!,
      scopes: (tokens.scope ?? '').split(' '),
    });
    return tokens.access_token;
  });
}

​

Si la respuesta se perdió: el margen de 60 segundos

• pasaron menos de 60 segundos desde la renovación anterior;
• el access token que te dio esa renovación nunca se usó en la API.

​

Reutilización: la conexión se corta

​

Qué hacer ante invalid_grant

• No reintentes con el mismo refresh token: no va a funcionar.
• Marca la conexión con ese negocio como desconectada en tu sistema.
• Muéstrale al propietario un botón para volver a conectar tu app, que lo lleve por el flujo de Conectar un negocio.

​

Los permisos de un token renovado

​

Desconecta un negocio

curl -s -o /dev/null -w "%{http_code}\n" https://api.craqui.com/oauth/revoke \
  -u "$CRAQUI_CLIENT_ID:$CRAQUI_CLIENT_SECRET" \
  -d token="$CRAQUI_REFRESH_TOKEN"

• La respuesta es 200 sin cuerpo, también si el token ya estaba revocado o no es de tu app (RFC 7009).
• Revocar un access token corta solo ese token; la conexión y su refresh siguen.
• Después de revocar, borra los tokens de ese negocio de tu base de datos.

const { refreshToken } = await loadConnection(businessId);
const response = await oauth.revocationRequest(as, client, clientAuth, refreshToken);
await oauth.processRevocationResponse(response);

​

Cuando el negocio desconecta tu app

• la API responde 401 app_connection_revoked a los access tokens de ese negocio;
• /oauth/token responde invalid_grant al refresh token.