Skip to main content

​
Visão geral

Tokens de Acesso Pessoal (PATs) permitem que usuários humanos se autentiquem programaticamente com sua própria identidade. Ao contrário das chaves de API de usuário de serviço (que autenticam como um usuário de serviço não humano), um PAT autentica como você — o usuário humano que criou o token. Todas as credenciais de API usam o formato de prefixo cog_. Ambos os tipos de token são usados da mesma forma no cabeçalho Authorization:

​
Escopo e permissões

Um PAT pertence a você, dentro da sua conta (sua conta Teams ou Enterprise). Ele não está vinculado a uma única organização, e não existe “PAT de organização” nem “PAT Enterprise”. Isso é diferente dos usuários de serviço, que são criados no nível da organização ou da Enterprise. Cada requisição seleciona a organização. Os endpoints de organização a identificam no caminho da URL (/v3/organizations/{org_id}/...), e a requisição é autorizada de acordo com seu acesso e sua função nessa organização. Uma requisição para uma organização à qual você não tem acesso falha. O token tem as mesmas permissões que seu usuário. Tudo o que você pode fazer no app web, também pode fazer com seu PAT, e nada além disso. Para criar, rotacionar ou revogar PATs, você precisa da permissão Gerenciar chaves de API na organização cujas configurações está visualizando ou de Gerenciar chaves de API da conta no nível da conta. Essa permissão controla quem pode gerenciar tokens; ela não altera o que um token pode fazer. As contas Enterprise também têm uma organização interna que armazena apenas configurações de toda a Enterprise. Ela não é um workspace. Requisições com PAT direcionadas a ela são rejeitadas com 403; portanto, sempre use o ID de uma organização filha.

​
Quando usar PATs

PATs foram criados para cenários em que você precisa de acesso programático à API em seu próprio nome:
  • Scripts e ferramentas pessoais — automatize seus próprios workflows sem um usuário de serviço compartilhado
  • Desenvolvimento local — teste integrações de API usando sua própria conta
  • Automação de curta duração — scripts pontuais que devem ser atribuídos a você
Para integrações em produção, pipelines de CI/CD e automações compartilhadas, use Chaves de API de usuários de serviço. Usuários de serviço oferecem melhores trilhas de auditoria, gerenciamento centralizado de chaves e controles de RBAC. Se não tiver certeza de qual usar, consulte a comparação.

​
Como criar e gerenciar PATs

Gerencie seus PATs na aba PATs da página de Configurações da Devin API, em qualquer organização ou nas configurações Enterprise. A aba mostra os mesmos tokens em ambos os casos (consulte Escopo e permissões).
  1. Crie um PAT — dê a ele um nome e uma data de expiração. O token começa com cog_ e é exibido apenas uma vez, no momento da criação.
  2. Use o token no cabeçalho Authorization — exatamente como uma chave de API de usuário de serviço. Cada chamada à API é autenticada usando sua conta de usuário: suas permissões, associações a orgs e trilha de auditoria se aplicam.
  3. Faça a rotação de um PAT — gere um novo segredo para um token existente sem alterar seu nome; o segredo antigo deixa de funcionar imediatamente.
  4. Revogue um PAT — invalide o token a qualquer momento.
PATs também são aceitos por endpoints em tempo real, como o WebSocket ao vivo do ACP, permitindo que ferramentas como o Devin CLI e clientes de desktop se autentiquem com um PAT.

​
Governança do Enterprise

Para contas Enterprise, a disponibilidade de PATs é controlada por uma política de PATs válida para todas as organizações do Enterprise. Os admins do Enterprise com Gerenciar configurações do Enterprise configuram a política (e tratam requisições de aprovação) na aba Políticas de PAT da página de configurações da Devin API do Enterprise.

​
Modos de política

​
Política de expiração

Quando os PATs estão ativados em uma Enterprise, todo PAT deve ter uma data de expiração, limitada pela duração máxima definida na política (365 dias por padrão; os administradores podem configurar um limite menor). Contas não Enterprise (Teams) podem criar PATs sem data de expiração.

​
Fluxo de aprovação

Em Aprovação necessária:
  1. Um membro solicita um PAT na aba PATs (nome + data de expiração).
  2. Os admins do Enterprise veem a solicitação na Fila de aprovação e a aprovam ou negam.
  3. Após a aprovação, o membro conclui a solicitação para gerar o token (exibido apenas uma vez).
  4. As solicitações pendentes expiram automaticamente após 7 dias se nenhuma ação for tomada.
Solicitantes e admins são notificados por e-mail em cada etapa do ciclo de vida do token (solicitado, aprovado, negado, revogado).

​
Inventário e revogação de tokens

Os admins do Enterprise com Gerenciar chaves de API da conta podem:
  • Visualizar todos os PATs da empresa no inventário de tokens, incluindo o status de conformidade com a política atual
  • Revogar tokens em massa (por exemplo, após tornar a política mais restritiva)
Tornar a política mais restritiva (ou desabilitar PATs) cancela as requisições pendentes afetadas, e o inventário sinaliza os tokens existentes que não estão mais em conformidade.

​
Revogação automática

Os PATs de um usuário são revogados automaticamente quando ele deixa de fazer parte da conta, inclusive em remoções por desprovisionamento via SCIM ou alterações no grupo do IdP.

​
Considerações de segurança

  • Trate os PATs com o mesmo cuidado que senhas — eles dão acesso total à sua conta
  • Armazene os PATs em variáveis de ambiente ou gerenciadores de segredos, nunca no código-fonte
  • Defina o menor prazo de expiração que funcione para o seu caso de uso
  • Revogue os PATs imediatamente se forem comprometidos
  • Prefira chaves de API de usuários de serviço para qualquer automação compartilhada ou de produção

​
Próximas etapas