Pular para o conteúdo principal
A API do Devin usa um modelo de principal + token. Um principal é quem você é (sua identidade), e um token é como você comprova isso (sua credencial). Entender essa distinção é fundamental para escolher o método de autenticação certo para seu caso de uso.

​
Principais & tokens

Todas as credenciais de API usam o formato de prefixo cog_. Inclua seu token no cabeçalho Authorization de cada requisição:
A distinção principal é como qual principal o token autentica:
  • Uma Chave de API de usuário de serviço autentica como o usuário de serviço — aplicam-se a identidade, as permissões e as associações à org do usuário de serviço.
  • Um Token de acesso pessoal autentica como o usuário humano que o criou — aplicam-se a identidade, as permissões e as associações à org desse usuário.
Usuários de serviço são contas não vinculadas a pessoas, criadas para integrações com APIs. Eles podem receber permissões específicas via RBAC e ser adicionados a organizações independentemente de usuários humanos.

​
Como funciona

  1. Crie um usuário de serviço em Settings > Service users (organization) ou Enterprise settings > Service users (enterprise)
  2. Atribua uma função que defina quais endpoints o usuário de serviço pode acessar
  3. Gere uma chave de API — a chave começa com cog_ e é exibida apenas uma vez no momento da criação
  4. Use a chave no cabeçalho Authorization de todas as requisições de API

​
Escopos de usuário de serviço

Encontre o ID da sua organização na página Settings > Service Users.

​
Atribuição de sessão com create_as_user_id

Usuários de serviço são identidades separadas dos usuários humanos. Por padrão, as sessões criadas por um usuário de serviço são atribuídas ao próprio usuário de serviço. Para criar sessões em nome de um usuário específico, passe o parâmetro create_as_user_id ao criar uma sessão. A sessão aparecerá na lista de sessões desse usuário e será contabilizada no uso dele. Isso requer a permissão ImpersonateOrgSessions na função do usuário de serviço.

​
Propriedades principais

  • As chaves começam com cog_ e são exibidas apenas uma vez, no momento da criação
  • Usuários de serviço aparecem separadamente de usuários humanos nos logs de auditoria
  • As permissões são controladas via RBAC — conceda apenas o que a integração precisa
  • Usuários de serviço Enterprise herdam permissões em nível de organização em todas as organizações
Para obter instruções detalhadas de configuração, consulte o guia de início rápido do Teams ou o guia de início rápido do Enterprise.

​
Tokens de acesso pessoal (beta fechado)

Os Tokens de Acesso Pessoal estão atualmente em beta fechado e são habilitados por feature flag. Entre em contato com o suporte para solicitar acesso. PATs não estão disponíveis para contas com SSO/Enterprise.
Tokens de acesso pessoal (PATs) permitem que usuários humanos se autentiquem de forma programática com a própria identidade. Quando você usa um PAT, a API vê você — suas permissões, suas associações a orgs e sua trilha de auditoria. Isso é útil quando você quer fazer chamadas à API como você mesmo (por exemplo, em scripts pessoais ou ferramentas locais), em vez de usar um usuário de serviço compartilhado. Para mais detalhes, consulte Tokens de acesso pessoal.

​
Autenticação legada (descontinuada)

As chaves de API legadas estão descontinuadas. Use a API v3 com autenticação de usuário de serviço. Consulte o guia de migração.
As chaves de API legadas são usadas com as APIs v1 e v2. Elas continuam funcionando durante o período de descontinuação, mas não são compatíveis com novos recursos como RBAC, atribuição de sessão ou paginação baseada em cursor. Onde gerar: Settings > API Keys

​
Melhores práticas de segurança

Nunca compartilhe chaves de API em áreas acessíveis publicamente, como repositórios GitHub, código no lado do cliente ou logs.
  1. Armazene as chaves com segurança: Use variáveis de ambiente ou sistemas de gerenciamento de segredos
  2. Rotacione as chaves regularmente: Gere novas chaves e revogue as antigas periodicamente
  3. Use usuários de serviço para automação: Prefira usuários de serviço em vez de chaves pessoais em produção
  4. Aplique o princípio do menor privilégio: Conceda apenas as permissões mínimas necessárias
  5. Monitore o uso: Revise os logs de auditoria em busca de atividade inesperada na API
  6. Revogue imediatamente chaves comprometidas: Se uma chave for exposta, revogue-a e gere uma nova

​
Solução de problemas

​
401 Não autorizado

Possíveis causas:
  • Chave de API inválida ou expirada
  • Cabeçalho Authorization ausente
  • Formato incorreto do token Bearer
  • Uso de uma chave de API legada (apk_ / apk_user_) com o Devin MCP — somente chaves com prefixo cog_ são compatíveis
Solução: Verifique se sua chave de API está correta e configurada adequadamente no cabeçalho Authorization. Para uso com MCP, certifique-se de que está usando uma chave de API de usuário de serviço (não uma chave legada).

​
403 Proibido

Possíveis causas:
  • A chave de API não tem as permissões necessárias
  • Uso do tipo de chave errado para o endpoint (por exemplo, chave legada com endpoints v3)
  • Tentativa de acessar recursos fora do seu escopo
Solução:
  • Garanta que o seu usuário de serviço tenha as funções e permissões corretas
  • Para endpoints legados v2: garanta que você tenha a função Enterprise Admin
  • Para endpoints legados v1: verifique se você tem acesso à organização

​
404 Não encontrado

Possíveis causas:
  • URL do endpoint da API incorreta
  • O recurso não existe ou você não tem acesso a ele
Solução: Verifique a URL do endpoint da API e se o recurso existe.

​
Próximos passos