Pular para o conteúdo principal
Usuários de serviço são contas de bot dedicadas para acesso à API, com permissões baseadas em função. Esse é o método de autenticação recomendado para todas as novas integrações.

​
Como funciona

  1. Crie um usuário de serviço em Settings > Service users
  2. Atribua uma função que defina quais endpoints o usuário de serviço pode acessar
  3. Gere uma chave de API (começa com cog_)
  4. Inclua a chave no cabeçalho Authorization de todas as requisições
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

EscopoCriado emAcesso à APICaso de uso
OrganizaçãoSettings > Service users/v3/organizations/*Gerenciamento de sessões, Knowledge, playbooks, segredos
EnterpriseEnterprise 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.

​
Atribuição de sessão com create_as_user_id

Usuários de serviço são identidades separadas de usuários humanos. Por padrão, 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 role do usuário de serviço.
Migrando de chaves de API pessoais? Chaves de API pessoais (v1/v2) criavam automaticamente sessões como o seu usuário. Com usuários de serviço, use create_as_user_id para obter o mesmo comportamento — com RBAC adicional, registros de auditoria e gerenciamento centralizado de chaves. Consulte a visão geral da API para um exemplo.

​
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.

​
Chaves de API legadas

As chaves de API legadas estão sendo descontinuadas e substituídas por usuários de serviço. Recomendamos migrar integrações existentes para usuários 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.
Tipo de chavePrefixoUsada comDescrição
Chave de API pessoalapk_user_v1, v2Vinculada a uma conta de usuário, herda as permissões do usuário
Chave de API de serviçoapk_v1Com escopo de organização, para automação
Onde gerar: Settings > API Keys

​
Autenticação com token Bearer

Todas as APIs do Devin usam autenticação por token Bearer. Inclua sua chave no cabeçalho Authorization: 
Authorization: Bearer your_api_key_here
Isso se aplica às credenciais de usuário de serviço e às chaves de API legadas.

​
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
Solução: Verifique se sua chave de API está correta e configurada adequadamente no cabeçalho Authorization.

​
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