Saltar al contenido principal

Claves de API y autenticación

Actualización

⚠️ Antes de comenzar, asegúrese de haber revisado los requisitos previos.

Esta guía explica cómo obtener credenciales para autenticarse con la API de Read AI mediante programación. La API de Read AI utiliza OAuth 2.1 con registro dinámico de clientes.

Admitimos la concesión de tipo Código de autorización con tokens de actualización para obtener y renovar tokens de acceso.

Para llamar a la API:

  1. Registre un cliente OAuth 2.1 mediante el registro dinámico de clientes.

  2. Obtenga un código de autorización mediante el flujo de Código de autorización.

  3. Intercambie el código de autorización por tokens de acceso y de actualización.

  4. Utilice el token de acceso para realizar solicitudes a la API.

  5. Actualice el token de acceso según sea necesario mediante el token de actualización.

Consejo: Recomendamos añadir | jq .  al final de todas las solicitudes curl para que los resultados sean más fáciles de interpretar visualmente

Paso 1: Registre su cliente OAuth

Este primer paso debe realizarse desde una interfaz de línea de comandos utilizando, por ejemplo, curl. 

IMPORTANTE: Guarde inmediatamente su client_id y client_secret. El client_secret es confidencial y debe almacenarse de forma segura.

Ejemplo de llamada a la API

curl -X POST https://api.read.ai/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My Analytics Dashboard",
    "redirect_uris": ["https://api.read.ai/oauth/ui"],   
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "scope": "openid email offline_access profile meeting:read mcp:execute",
    "token_endpoint_auth_method": "client_secret_basic"
  }'

Puede especificar cualquier valor que desee para client_name, pero todos los demás detalles deben dejarse sin modificar. 

Ejemplo de respuesta

{
  "client_id": "test_id",
  "client_name": "My Analytics Dashboard",
  "client_secret": "super_secret",
  "redirect_uris": ["https://api.read.ai/oauth/ui"],
  "token_endpoint_auth_method": "client_secret_basic",
  "allowed_cors_origins": [],
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "scope": "openid email meeting:read offline_access profile mcp:execute",
  "audience": [
    "https://api.read.ai/v1/meetings",
    "https://api.read.ai/mcp"
  ],
  "registration_client_uri": "https://authn.read.ai/oauth2/register",
  "registration_access_token": "access_token"
}

Recuerde guardar su client_id y client_secret, ya que no se pueden recuperar más adelante.

Paso 2: Obtenga un código de autorización

Este paso se realiza en un navegador web, desde la página de OAuth de Read AI.

Inicie el flujo de OAuth

Vaya a https://api.read.ai/oauth/ui y:

  • Introduzca su identificador de cliente y secreto de cliente del registro dinámico de clientes.
  • La URI de redirección ya debería aparecer rellenada correctamente como https://api.read.ai/oauth/ui.
  • Haga clic en Iniciar flujo de OAuth cuando esté listo para continuar.

Inicie sesión en Read AI

Si todavía no ha iniciado sesión en Read AI en su navegador, se le dirigirá a la página de inicio de sesión de Read AI, donde deberá iniciar sesión con su cuenta.

Aunque todas las opciones de SSO deberían funcionar, algunos usuarios han informado que no se les redirige automáticamente a la pantalla de consentimiento de OAuth después de iniciar sesión. Si esto sucede, puede reiniciar el proceso en https://api.read.ai/oauth/ui y debería omitirse el paso de inicio de sesión, ya que ya está autenticado.

Pantalla de consentimiento

Haga clic en Permitir acceso para dar su consentimiento a todos los ámbitos que se concederán a su token de acceso. 

Pantalla del código de autorización

¡En este momento ya ha recibido su código de autorización! En el siguiente paso, intercambiará este código por un par de tokens de acceso y de actualización. La forma más sencilla de hacerlo es hacer clic en Copiar comando y pegarlo después en su CLI.

 

Paso 3: Intercambie el código de autorización por tokens

Vuelva a la interfaz de línea de comandos y ejecute el comando que copió al final del paso anterior. Asegúrese de copiar y guardar de forma segura los valores de access_token y refresh_token .

Ejemplo de solicitud

curl -X POST https://authn.read.ai/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic $(echo -n 'REDACTED' | base64)" \
  -d "grant_type=authorization_code" \
  -d "code=REDACTED" \
  -d "redirect_uri=https://api.read.ai/oauth/ui" \
  -d "code_verifier=REDACTED"

Ejemplo de respuesta

{
  "access_token": "REDACTED",
  "expires_in": 599,
  "id_token": "REDACTED",
  "refresh_token": "REDACTED",
  "scope": "openid profile email meeting:read mcp:execute offline_access",
  "token_type": "bearer"
}

Paso 4: Utilice el token de acceso para realizar llamadas a la API

Ahora puede utilizar el token de acceso para autenticar solicitudes a la API REST incluyéndolo en el encabezado Authorization como token Bearer.

Ejemplo de solicitud

curl -X GET "https://api.read.ai/oauth/test-token-with-scopes" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Este es un endpoint sencillo para realizar pruebas. Para consultar la lista completa de endpoints de API disponibles y otros detalles de especificación, consulte la página Referencia de la API.

Paso 5: Actualice el token de acceso según sea necesario

Los tokens de acceso caducan después de 10 minutos y deben actualizarse para continuar realizando solicitudes a la API.

Para obtener un nuevo token de acceso, envíe una solicitud al endpoint de tokens de OAuth utilizando la concesión refresh_token.

Importante: Los tokens de actualización se rotan cada vez que se utilizan, con un breve período de gracia para facilitar la simultaneidad. El endpoint de tokens devolverá un nuevo token de actualización cada vez que intercambie uno. Debe conservar de forma segura el nuevo token de actualización y descartar el anterior.

Ejemplo de solicitud

curl -X POST https://authn.read.ai/oauth2/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -u "CLIENT_ID:CLIENT_SECRET" \
    -d "grant_type=refresh_token" \
    -d "refresh_token=YOUR_REFRESH_TOKEN"

Consejos para solucionar problemas

  • Guarde inmediatamente el nuevo token de actualización de cada respuesta de actualización en un almacenamiento persistente y descarte el anterior.
  • Permita que solo un proceso realice la actualización a la vez. Si varios trabajadores comparten la conexión, haga que lean de un único almacén de tokens y establezca un bloqueo durante la actualización.
  • Si una llamada de actualización falla con un error 5xx o agota el tiempo de espera, vuelva a intentarlo inmediatamente con el mismo token de actualización. No espere hasta la próxima actualización programada. El período de gracia está pensado para cubrir este caso, pero es breve.

Artículos relacionados