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.
| Principal | Token | Descrição |
|---|
| Usuário de serviço (não humano) | Chave de API de usuário de serviço | Para integrações automatizadas e pipelines de CI/CD |
| Usuário (humano) | Token de acesso pessoal (PAT) | Para acesso programático humano com a sua própria identidade |
cog_. Inclua seu token no cabeçalho Authorization de cada requisição:
curl -X GET "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
-H "Authorization: Bearer cog_your_token_here"
- 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 (recomendado para automação)
- Crie um usuário de serviço em Settings > Service users (organization) ou Enterprise settings > Service users (enterprise)
- Atribua uma função que defina quais endpoints o usuário de serviço pode acessar
- Gere uma chave de API — a chave começa com
cog_ e é exibida apenas uma vez no momento da criação
- Use a chave no cabeçalho
Authorization de todas as requisições de API
curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
-H "Authorization: Bearer $DEVIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "Create a simple Python script"}'
Escopos de usuário de serviço
| Escopo | Criado em | Acesso à API | Caso de uso |
|---|
| Organização | Settings > Service users | /v3/organizations/* | Gerenciamento de sessões, Knowledge, playbooks, segredos |
| Enterprise | Enterprise settings > Service users | /v3/enterprise/* + /v3/organizations/* | Gerenciamento entre organizações, análises, logs de auditoria, faturamento |
Encontre o ID da sua organização na página Settings > Service Users.
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.
- 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.
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. | Tipo de chave | Prefixo | Usada com | Descrição |
|---|
| Chave de API pessoal | apk_user_ | v1, v2 | Vinculada a uma conta de usuário, herda as permissões do usuário |
| Chave de API de serviço | apk_ | v1 | Com escopo de organização, para automação |
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.
- Armazene as chaves com segurança: Use variáveis de ambiente ou sistemas de gerenciamento de segredos
- Rotacione as chaves regularmente: Gere novas chaves e revogue as antigas periodicamente
- Use usuários de serviço para automação: Prefira usuários de serviço em vez de chaves pessoais em produção
- Aplique o princípio do menor privilégio: Conceda apenas as permissões mínimas necessárias
- Monitore o uso: Revise os logs de auditoria em busca de atividade inesperada na API
- Revogue imediatamente chaves comprometidas: Se uma chave for exposta, revogue-a e gere uma nova
Possíveis causas:
- Chave de API inválida ou expirada
- Cabeçalho
Authorization ausente
- Formato incorreto do token Bearer
Solução: Verifique se sua chave de API está correta e configurada adequadamente no cabeçalho Authorization.
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
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.
