Saltar al contenido principal

Claves de API y autenticación

Actualización

⚠️ Antes de comenzar, asegúrate de haber revisado los requisitos previos en Leer la descripción general de la API y MCP de Read.

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

Nota: Read no emite claves de API estáticas ni de larga duración para la API de Read. En su lugar, debes autenticarte con tokens de acceso OAuth de corta duración, que se renuevan con un token de actualización, como se describe a continuación. (La opción Generar clave de API en la página de integración de Zapier crea una clave para conectar Read con Zapier; consulta Introducción a Zapier.)

Read admite la concesión de código de autorización con tokens de actualización para obtener y renovar tokens de acceso.

Para llamar a la API:

  1. Registra un cliente OAuth 2.1 mediante el registro dinámico de clientes.
  2. Obtén un código de autorización mediante el flujo de código de autorización.
  3. Intercambia el código de autorización por tokens de acceso y de actualización.
  4. Usa el token de acceso para realizar solicitudes a la API.
  5. Actualiza el token de acceso según sea necesario mediante el token de actualización.
Consejo: Recomendamos añadir | jq . al final de tus solicitudes curl para facilitar la lectura de los resultados.

Paso 1: Registra tu cliente OAuth

Realiza este paso desde una interfaz de línea de comandos, usando una herramienta como curl.

Importante: Guarda inmediatamente tu 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"
  }'

Puedes usar cualquier valor que quieras para client_name. Deja todos los demás detalles sin cambios, a menos que quieras que tu cliente envíe sus credenciales en el cuerpo de la solicitud (consulta Método de autenticación del cliente a continuación).

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"
}

Recuerda guardar tu client_id y client_secret. No podrás recuperarlos más adelante.

Método de autenticación del cliente

El token_endpoint_auth_method que estableces al registrar determina cómo debe enviar tu aplicación su ID y secreto de cliente al punto de conexión de tokens en los pasos 3 y 5. Se admiten dos métodos:

  • client_secret_basic (usado en el ejemplo anterior): envía el ID y el secreto de cliente en un encabezado HTTP Basic Authorization.
  • client_secret_post: envía client_id y client_secret como campos de formulario en el cuerpo de la solicitud. Para usar este método, establece "token_endpoint_auth_method": "client_secret_post" en tu solicitud de registro.

Si tu aplicación envía las credenciales de una forma distinta al método con el que la registraste, el punto de conexión de tokens rechaza la solicitud con 401 Unauthorized. Para cambiar de método, registra un nuevo cliente con el método que quieras y completa de nuevo los pasos 2 y 3. Los tokens de un cliente no funcionan con las credenciales de otro cliente.

Paso 2: Obtén un código de autorización

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

Inicia el flujo de OAuth

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

  1. Introduce tu ID de cliente y secreto de cliente del registro dinámico de clientes.
  2. Comprueba que el URI de redireccionamiento ya esté completado como https://api.read.ai/oauth/ui.
  3. Haz clic en Iniciar flujo de OAuth cuando estés listo.

Inicia sesión en Read AI

Si aún no has iniciado sesión en Read AI desde tu navegador, se te enviará a la página de inicio de sesión de Read AI. Inicia sesión con tu cuenta.

Todas las opciones de inicio de sesión único (SSO) deberían funcionar, pero algunos usuarios han informado que no se les redirigió automáticamente a la pantalla de consentimiento de OAuth después de iniciar sesión. Si esto sucede, reinicia el proceso en https://api.read.ai/oauth/ui. Como ya has iniciado sesión, debería omitir el paso de inicio de sesión.

Pantalla de consentimiento

Haz clic en Permitir acceso para conceder todos los alcances enumerados a tu token de acceso.

Pantalla del código de autorización

¡Ya tienes tu código de autorización! En el siguiente paso, lo intercambiarás por un token de acceso y un token de actualización. La forma más sencilla es hacer clic en Copiar comando y pegar el comando en tu interfaz de línea de comandos.

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

Vuelve a tu interfaz de línea de comandos y ejecuta el comando que copiaste al final del paso anterior. Copia y guarda de forma segura los valores de access_token y refresh_token.

Solicitud de ejemplo

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"

Respuesta de ejemplo

{
  "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: Usa el token de acceso para realizar llamadas a la API

Ahora puedes autenticar solicitudes a la API REST incluyendo el token de acceso en el encabezado Authorization como un token Bearer.

Solicitud de ejemplo

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

Este es un punto de conexión sencillo para realizar pruebas. Para consultar la lista completa de puntos de conexión de la API y otros detalles de la especificación, consulta Referencia de la API.

Paso 5: Actualiza 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 token de acceso nuevo, envía una solicitud al punto de conexión de tokens de OAuth usando la concesión refresh_token.

Duración de los tokens

  • Token de acceso: 10 minutos.
  • Token de actualización: aproximadamente 6 meses (4380 horas o 182,5 días).
  • Período de gracia para un token de actualización reemplazado: después de una actualización, el token de actualización anterior sigue funcionando durante un máximo de 10 minutos después de que se emita el nuevo, o durante 5 usos más, lo que ocurra primero. Después de eso, se rechaza.

Importante: Los tokens de actualización rotan cada vez que se usan. El punto de conexión de tokens devuelve un token de actualización nuevo cada vez que intercambias uno. Debes conservar de forma segura el token de actualización nuevo y descartar el anterior. El período de gracia existe para gestionar solicitudes simultáneas y llamadas de actualización fallidas, no para seguir usando el token anterior.

Solicitud de ejemplo (client_secret_basic)

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"

Solicitud de ejemplo (client_secret_post)

Usa este formato únicamente si registraste tu cliente con "token_endpoint_auth_method": "client_secret_post".

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

Consejos para solucionar problemas

  • Guarda inmediatamente el nuevo token de actualización de cada respuesta de actualización en un almacenamiento persistente y descarta el anterior.
  • Permite que solo un proceso actualice a la vez. Si varios trabajadores comparten la conexión, haz que lean de un único almacén de tokens y establece un bloqueo durante la actualización.
  • Si una llamada de actualización falla con un error 5xx o agota el tiempo de espera, vuelve a intentarlo inmediatamente con el mismo token de actualización. No esperes a la siguiente actualización programada. El token de actualización anterior solo sigue funcionando durante un máximo de 10 minutos después de que se emita uno nuevo, o durante 5 usos más, lo que ocurra primero.
  • ¿Aparece 401 Unauthorized al actualizar? Comprueba que envías el ID y el secreto de cliente de la forma en que se registró tu cliente: en un encabezado Authorization Basic para client_secret_basic, o como campos de formulario para client_secret_post. Asegúrate también de usar el token de actualización más reciente y el ID y secreto de cliente del mismo registro que lo emitió.
  • Los tokens de actualización caducan después de aproximadamente 6 meses. Si tu token de actualización ha caducado, repite los pasos 2 y 3 para obtener tokens nuevos.

Artículos relacionados