Devin oferece várias versões de API com diferentes mecanismos de autenticação e modelos de autorização. Entender qual tipo de Chave de API usar é essencial para uma integração adequada.
Resumo das versões da API
| Versão | Autenticação | Modelo de autorização |
|---|
| v1 | Chaves de API pessoais ou de serviço | Escopo da organização |
| v2 | Chaves de API pessoais | Somente administrador Enterprise |
| v3 (Beta) | Credenciais de usuário de serviço | RBAC completo |
| Tipo de Chave de API | Prefixo | Descrição |
|---|
| Chave de API pessoal | apk_user_ | Chaves com escopo de usuário e organização que herdam as permissões individuais do usuário |
| Chave de API de serviço | apk_ | Chaves de serviço com escopo de organização para automação |
| Credencial de usuário de serviço | cog_ | Credenciais de usuário de serviço com escopo de Enterprise/organização e RBAC |
- Navegue até Settings > API Keys em qualquer sub-organização
- Clique em “Generate New API Key”
- Copie e armazene a chave com segurança (ela será exibida apenas uma vez)
Versões de API compatíveis:
- v1: Sim - herda as permissões em nível de org do usuário
- v2: Sim - apenas para usuários com o papel Enterprise Admin
- v3: Não - use Service User Credentials em vez disso
Casos de uso recomendados:
- Scripts pessoais de automação
- Desenvolvimento e testes
- Integrações específicas de usuário
Considerações de segurança:
- As chaves são limitadas às permissões do usuário
- Revogar o acesso de um usuário invalida automaticamente suas chaves de API
- As chaves devem ser rotacionadas regularmente
Chaves de API de serviço podem ser geradas em sub-organizações sob certas condições.
Onde gerar:
Versões de API compatíveis:
- v1: Sim - com escopo de organização
- v2: Não - não é compatível
- v3: Não - use Service User Credentials em vez disso
Casos de uso recomendados:
- Automação no nível da organização
- Pipelines de CI/CD com escopo definido para equipes específicas
- Ferramentas compartilhadas dentro de uma sub-organização
Credenciais de usuário de serviço (somente v3)
- Navegue até Enterprise Settings > Service Users
- Clique em “Create Service User”
- Atribua os papéis apropriados (Enterprise Admin, Org Admin, Org Member, etc.)
- Gere uma Chave de API para o usuário de serviço
Tipos de usuário de serviço:
- Enterprise Service Users: Podem acessar várias organizações com base nos papéis atribuídos
- Organization Service Users: Limitados a organizações específicas com papéis em nível de organização
Versões de API compatíveis:
- v1: Não - não disponível
- v2: Não - não disponível
- v3: Sim - suporte completo a RBAC
Casos de uso recomendados:
- Automação em produção com permissões granulares
- Fluxos de trabalho com múltiplas organizações
- Integrações com requisitos de conformidade que exigem trilhas de auditoria
- Integrações de longa duração com escopos de permissão específicos
Considerações de segurança:
- Usuários de serviço aparecem nos logs de auditoria separadamente de usuários humanos
- As permissões podem ser controladas com precisão via RBAC
- As chaves podem ser rotacionadas sem afetar contas de usuários humanos
- Ideal para o princípio do menor privilégio
Todas as APIs do Devin usam autenticação por token Bearer. Inclua sua chave de API no cabeçalho Authorization:
Authorization: Bearer your_api_key_here
curl -X POST "https://api.devin.ai/v1/sessions" \
-H "Authorization: Bearer YOUR_V1_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Crie um script Python simples"
}'
curl -X GET "https://api.devin.ai/v2/enterprise/organizations" \
-H "Authorization: Bearer YOUR_V2_ENTERPRISE_ADMIN_KEY"
curl -X GET "https://api.devin.ai/v3beta1/enterprise/organizations" \
-H "Authorization: Bearer YOUR_V3_SERVICE_USER_KEY"
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 v3 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 da versão de API incorreta para o tipo da sua chave (por exemplo, chave pessoal com v3)
- Tentativa de acessar recursos fora do seu escopo
Solução:
- Para v2: garanta que você tenha a função Enterprise Admin
- Para v3: use uma credencial de usuário de serviço com funções apropriadas
- Para 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 se a URL do endpoint corresponde à versão da API que você está usando e se o recurso existe.
