> ## Documentation Index > Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt > Use this file to discover all available pages before exploring further. # Autenticação > Entenda principals, tokens e como se autenticar com a API do Devin 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
| 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 | Todas as credenciais de API usam o formato de prefixo `cog_`. Inclua seu token no cabeçalho `Authorization` de cada requisição: ```bash theme={null} curl -X GET "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \ -H "Authorization: Bearer cog_your_token_here" ``` 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 ```bash theme={null} 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**.
### 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](/pt-BR/api-reference/getting-started/teams-quickstart) ou o [guia de início rápido do Enterprise](/pt-BR/api-reference/getting-started/enterprise-quickstart). ***
## 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](mailto:support@cognition.ai) 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](/pt-BR/api-reference/personal-access-tokens). ***
## Autenticação legada (descontinuada)
As chaves de API legadas estão descontinuadas. Use a [API v3](/pt-BR/api-reference/v3/overview) com autenticação de usuário de serviço. Consulte o [guia de migração](/pt-BR/api-reference/getting-started/migration-guide). 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 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 | **Onde gerar:** [Settings > API Keys](https://app.devin.ai/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](/pt-BR/work-with-devin/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
* [Início rápido do Teams](/pt-BR/api-reference/getting-started/teams-quickstart) — comece em poucos minutos * [Início rápido do Enterprise](/pt-BR/api-reference/getting-started/enterprise-quickstart) — configuração de RBAC e de várias organizações * [Fluxos comuns](/pt-BR/api-reference/common-flows) — exemplos de workflow de ponta a ponta * [Guia de migração](/pt-BR/api-reference/getting-started/migration-guide) — migre a partir das versões v1/v2