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

Admins do Enterprise com a permissão Gerenciar chaves de API da conta podem abrir a visualização PAT inventory na aba Políticas de PAT para:
  • Visualizar PATs de todo o Enterprise, com o nome, o proprietário, a data de criação, a data de expiração e o status (Active, Revoked ou Expired) de cada token. Filtre por status ou pesquise por nome ou proprietário.
  • Revogar um token ativo diretamente na linha correspondente. O inventário revoga um token por vez.
O inventário não indica se um token está em conformidade com a política atual. A conformidade é verificada quando você altera a política: se um novo modo ou um prazo máximo de expiração mais curto deixar tokens existentes fora de conformidade, uma caixa de diálogo de confirmação lista os tokens afetados e as respectivas violações antes de aplicar a alteração. Administradores sem a permissão Gerenciar chaves de API da conta veem apenas o número de tokens afetados. Ao confirmar, esses tokens são revogados e as requisições pendentes de seus proprietários são canceladas. Alterar a política para desativado revoga todos os PATs ativos e cancela todas as requisições pendentes.

​
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