orkasa
ENEntrar

Autenticación

OAuth 2.0

Para que una aplicación de terceros actúe en nombre de un corredor sin ver su contraseña.

Orkasa es un servidor de autorización OAuth 2.0 (RFC 6749). Es por donde entra Zapier, y es por donde entra el conector MCP.

URL
Autorizaciónhttps://orkasa.app/oauth/authorize
Tokenhttps://orkasa.app/api/oauth/token
Refrescohttps://orkasa.app/api/oauth/token

Concesiones: authorization_code (con PKCE S256) y refresh_token.

El flujo

Manda al corredor a autorizar

https://orkasa.app/oauth/authorize
  ?response_type=code
  &client_id=ork_client_…
  &redirect_uri=https%3A%2F%2Fejemplo.com%2Fcallback
  &scope=leads%3Aread%20leads%3Awrite%20viewings%3Awrite
  &state=<valor aleatorio anti-CSRF>
  &code_challenge=…&code_challenge_method=S256

La pantalla de consentimiento nombra la aplicación, la agencia a la que va a llegar y cada permiso en lenguaje llano. Si no ha iniciado sesión, entra primero y vuelve exactamente a esa URL.

Orkasa devuelve un código

…/callback?code=ork_ac_…&state=<tu state>

Si rechaza: ?error=access_denied&state=…. Tu state vuelve intacto.

Canjea el código por tokens

curl -X POST https://orkasa.app/api/oauth/token \
  -d grant_type=authorization_code \
  -d client_id=ork_client_… \
  -d client_secret=ork_cs_… \
  -d code=ork_ac_… \
  -d code_verifier=… \
  --data-urlencode "redirect_uri=https://ejemplo.com/callback"
{
  "access_token": "ork_at_…",
  "refresh_token": "ork_rt_…",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "leads:read leads:write viewings:write"
}

Las credenciales del cliente también se aceptan como HTTP Basic.

Llama a la API

Authorization: Bearer ork_at_…, en cualquier endpoint, sin ningún cambio.

Refresca al cabo de una hora

curl -X POST https://orkasa.app/api/oauth/token \
  -u "ork_client_…:ork_cs_…" \
  -d grant_type=refresh_token \
  -d refresh_token=ork_rt_…

Los tokens de refresco rotan: cada refresco devuelve un par nuevo y revoca el anterior. Guarda siempre el refresh_token nuevo. Duran 60 días.

Errores

Los endpoints OAuth hablan RFC 6749, no el envoltorio de /api/v1:

{ "error": "invalid_grant", "error_description": "…" }

invalid_client (401) · invalid_grant, invalid_request, invalid_scope, unsupported_grant_type (400).

Todos los fallos de un código de autorización —desconocido, caducado, ya usado, cliente equivocado, redirect_uri equivocada, verificador PKCE malo— devuelven el mismo invalid_grant. Quien llama no puede sondear cuál fue.

Lo que sostiene el flujo

  • Los códigos son de un solo uso, caducan en 5 minutos y están atados al client_id que los pidió y a la redirect_uri exacta. El canje es atómico: una carrera no puede canjear el mismo dos veces.
  • La redirect_uri se compara por igualdad exacta contra la lista blanca registrada. Nunca por prefijo, nunca con comodines. Si el cliente o la URL no validan, Orkasa muestra el error en su propio dominio y no redirige a ninguna parte.
  • PKCE se verifica siempre que se registró un code_challenge, y solo se acepta S256.
  • Tokens, códigos y secretos se guardan como resúmenes SHA-256. Nada se registra en claro, y nada es recuperable después de la respuesta que lo emitió.
  • Revocar la fila de un token mata el de acceso y el de refresco a la vez — que es también como la rotación retira el par anterior.