Avançar para o conteúdo principal

Chaves de API e autenticação

Atualizado

⚠️ Antes de começar, certifique-se de ter revisado os pré-requisitos.

Este guia explica como obter credenciais para autenticar-se programaticamente com a API do Read AI. A API do Read AI usa OAuth 2.1 com registro dinâmico de cliente.

Oferecemos o grant de Código de autorização com tokens de atualização para obter e renovar tokens de acesso.

Para chamar a API:

  1. Registre um cliente OAuth 2.1 usando o registro dinâmico de cliente.

  2. Obtenha um código de autorização por meio do fluxo de Código de autorização.

  3. Troque o código de autorização por tokens de acesso e de atualização.

  4. Use o token de acesso para fazer solicitações à API.

  5. Atualize o token de acesso conforme necessário usando o token de atualização.

Dica: recomendamos acrescentar | jq .  a todas as solicitações curl para facilitar a interpretação visual das saídas

Etapa 1: registre seu cliente OAuth

Esta primeira etapa deve ser realizada em uma interface de linha de comando usando, por exemplo, o curl. 

IMPORTANTE: salve seu client_id e client_secret imediatamente. O client_secret é confidencial e deve ser armazenado com segurança.

Exemplo de chamada da 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"
  }'

Você pode especificar qualquer valor para client_name, mas todos os outros detalhes devem permanecer inalterados. 

Exemplo de resposta

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

Lembre-se de salvar seu client_id e client_secret, pois eles não poderão ser recuperados posteriormente.

Etapa 2: obtenha um código de autorização

Esta etapa ocorre em um navegador da web, na página OAuth do Read AI.

Inicie o fluxo OAuth

Acesse https://api.read.ai/oauth/ui e:

  • Insira seu ID do cliente e segredo do cliente obtidos no registro dinâmico de cliente.
  • O URI de redirecionamento já deve estar preenchido corretamente como https://api.read.ai/oauth/ui.
  • Clique em Iniciar fluxo OAuth quando estiver pronto para prosseguir.

Entre no Read AI

Se você ainda não estiver conectado ao Read AI no navegador, será encaminhado à página de login do Read AI, onde deverá entrar com sua conta.

Embora todas as opções de SSO devam funcionar, houve relatos de usuários que não foram redirecionados automaticamente de volta à tela de consentimento do OAuth após fazer login. Se isso acontecer, você poderá reiniciar o processo em https://api.read.ai/oauth/ui, que deverá ignorar a etapa de login, pois você já estará autenticado.

Tela de consentimento

Clique em Permitir acesso para consentir com todos os escopos que serão concedidos ao seu token de acesso. 

Tela do código de autorização

Neste ponto, você recebeu seu código de autorização! Na próxima etapa, você trocará esse código por um par de tokens de acesso/atualização. A maneira mais simples de fazer isso é clicar em Copiar comando e colá-lo na sua CLI.

 

Etapa 3: troque o código de autorização por tokens

Volte à sua interface de linha de comando e execute o comando copiado ao final da etapa anterior. Certifique-se de copiar e salvar com segurança os valores de access_token e refresh_token .

Exemplo de solicitação

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"

Exemplo de resposta

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

Etapa 4: use o token de acesso para fazer chamadas à API

Agora você pode usar o token de acesso para autenticar solicitações à API REST, incluindo-o no cabeçalho Authorization como um token Bearer.

Exemplo de solicitação

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

Este é um endpoint simples para fins de teste. Para obter uma lista completa dos endpoints da API disponíveis e outros detalhes da especificação, consulte a página Referência da API.

Etapa 5: atualize o token de acesso conforme necessário

Os tokens de acesso expiram após 10 minutos e devem ser atualizados para que você continue fazendo solicitações à API.

Para obter um novo token de acesso, envie uma solicitação ao endpoint de token OAuth usando o grant refresh_token.

Importante: os tokens de atualização são alternados a cada uso, com um curto período de tolerância para ajudar a lidar com a simultaneidade. O endpoint de token retornará um novo token de atualização cada vez que você trocar um token. Você deve persistir com segurança o novo token de atualização e descartar o anterior.

Exemplo de solicitação

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"

Dicas para solução de problemas

  • Salve imediatamente o novo token de atualização de cada resposta de atualização em um armazenamento persistente e descarte o antigo.
  • Permita que apenas um processo faça a atualização por vez. Se vários workers compartilharem a conexão, faça com que leiam de um único armazenamento de tokens e usem um bloqueio durante a atualização.
  • Se uma chamada de atualização falhar com um erro 5xx ou atingir o tempo limite, tente novamente imediatamente com o mesmo token de atualização. Não espere até a próxima atualização programada. O período de tolerância existe para cobrir esse caso, mas é curto.

Artigos relacionados