Gerenciamento de Tokens

Este recurso faz parte dos planos Team & Enterprise.

O gerenciamento de tokens permite que administradores de organização supervisionem os tokens de acesso dentro de sua organização, garantindo acesso seguro aos recursos da organização.

Para a experiência do membro quando as políticas de gerenciamento de tokens estão em vigor — incluindo como verificar o status do token, quais erros esperar e como a negação e a revogação afetam um token — consulte Tokens em organizações com políticas de gerenciamento de tokens.

Visualizando e gerenciando tokens de acesso

O recurso de listagem de tokens exibe todos os tokens de acesso dentro da sua organização. Os administradores podem:

• Monitore o uso de tokens e identifique ou previna riscos de segurança potenciais:
  • Acesso não autorizado a recursos privados (“vazamentos”)
  • Escopos de acesso excessivamente amplos
  • Higiene de tokens subótima (por exemplo, tokens que não foram rotacionados há muito tempo)
• Identificar tokens inativos ou não utilizados

Tokens de granularidade fina exibem suas permissões específicas:

Tokens revogados são ocultados da listagem por padrão. Use o alternador Mostrar tokens revogados acima da lista para incluí-los na visualização.

Um selo de status REVOKED é exibido para qualquer token revogado, independentemente da política de tokens da organização. Os selos PENDING, APPROVED e DENIED aparecem apenas em organizações com a política “Require administrator approval” ativada, pois esses estados são criados apenas pelo fluxo de aprovação.

Política de Token

Administradores de organizações Team & Enterprise podem impor as seguintes políticas:

Revisando a Autorização de Token

Quando a política de tokens é definida como “Require administrator approval”, os administradores da organização podem revisar os detalhes de todos os tokens de acesso granular que acessam recursos pertencentes à organização e aprovar ou negar o acesso. Quando um novo token entra no estado pendente, até 50 administradores da organização com endereços de e-mail confirmados recebem uma notificação com um link direto para a página de revisão do token. Nenhuma notificação é enviada quando um token é aprovado automaticamente (por exemplo, porque o criador é um administrador da organização).

• Tokens Pending estão aguardando uma decisão do administrador
• Tokens Aprovados foram autorizados e estão ativos
• Tokens Denied foram bloqueados de acessar os recursos da organização

Quando um token é aprovado ou negado, o proprietário do token recebe uma notificação por e-mail.

A negação não é permanente: um token negado pode ser aprovado posteriormente por um administrador, restaurando seu acesso. Da mesma forma, um token já aprovado pode ser negado a qualquer momento, o que remove seu acesso baseado em aprovação imediatamente.

Os nomes dos tokens são visíveis apenas para administradores quando a política “Exigir aprovação do administrador” está ativada.

O que os membros veem quando bloqueados

Membros cujos tokens estão pendentes ou negados recebem um erro 403 ao acessar recursos da organização: “Devido à política de tokens da organização, seu token precisa ser aprovado pela organização antes que você possa acessar este recurso.”

A mensagem de erro é a mesma para os estados pendente e negado. Para ver o status, os membros podem navegar para a página de edição do token individual. A página de configurações de gerenciamento de tokens do administrador da organização exibe selos de status para todos os tokens dos membros.

Negar vs. Revogar

Administradores têm duas formas de remover o acesso de um token a uma organização:

Use deny ao gerenciar o acesso dentro do fluxo de aprovação (o token passa para o estado denied e pode ser reaprovado posteriormente). Use revoke quando precisar cortar permanentemente o acesso de um token à organização.

Listando Tokens via API

A lista de tokens exibida na interface de configurações também está disponível programaticamente:

# ORG_NAME should be your organization name and ADMIN_HF_TOKEN an admin's access token
curl -H "Authorization: Bearer ${ADMIN_HF_TOKEN}" \
  "https://huggingface.co/api/organizations/${ORG_NAME}/settings/tokens"

A resposta é um array de tokens de acesso de membros. Consulte a referência OpenAPI para o esquema completo: GET /api/organizations/<name>/settings/tokens

Por padrão, tokens revogados são ocultados; passe q=status:all para incluí-los, como a alternância Mostrar tokens revogados na interface.

Revogando Tokens

Este recurso faz parte do plano Enterprise e dos planos superiores.

Administradores de organização podem revogar o token de acesso de qualquer membro a partir da página de detalhes do token. A revogação está disponível independentemente de a organização usar a política “Require administrator approval”. Um token revogado não pode mais acessar os recursos da organização, mas continua funcionando em outros locais. O proprietário do token recebe uma notificação por e-mail quando a revogação ocorre.

Tokens revogados permanecem revogados mesmo que a política de tokens da organização seja alterada ou desativada posteriormente. A revogação é permanente no nível da organização — não existe ação de desrevogação. Se um membro precisar que o acesso seja restaurado, ele deve excluir o token revogado e criar um novo. Se a organização utiliza a política “Require administrator approval”, o novo token começará no estado pendente e exigirá aprovação do administrador.

Membros cujos tokens foram revogados recebem um erro 403 com a mensagem: “Seu token foi revogado pelo administrador da organização, você não pode mais acessar os recursos da organização. Entre em contato com eles para obter mais informações.” Essa mensagem é exibida independentemente de a organização usar a política “Exigir aprovação do administrador”.

Revogando via API

Administrators também podem revogar um token programaticamente usando seu token id. Isso é útil para fluxos de trabalho automatizados, em que um token precisa ser revogado imediatamente.

# ORG_NAME should be your organization name and ADMIN_HF_TOKEN an admin's access token
# TOKEN_ID is the 24-character id shown on the org token settings page (or returned by the tokens listing API)
curl -X POST "https://huggingface.co/api/organizations/${ORG_NAME}/settings/tokens/${TOKEN_ID}/revoke" \
  -H "Authorization: Bearer ${ADMIN_HF_TOKEN}"

Um administrador não pode revogar o próprio token: uma solicitação cujo id do token corresponda ao token usado para autenticação é rejeitada com um erro 403.

Este endpoint apenas revoga o acesso do token à sua organização; o token continua funcionando para os outros recursos do proprietário. Para invalidar um token vazado em todos os lugares, use POST /api/credentials/revoke em vez disso, que não requer autenticação e aceita um lote de valores de token brutos.

Emissão Programática de Tokens

Este recurso faz parte do plano Enterprise e dos planos superiores.

Para organizações que precisam emitir tokens de acesso programaticamente para seus membros (por exemplo, para plataformas internas, pipelines de CI/CD ou integrações personalizadas), consulte OAuth Token Exchange. Este recurso do plano Enterprise permite que seus serviços de backend emitam tokens com escopo para membros da organização sem exigir consentimento interativo do usuário.

Contas de serviço

Este recurso faz parte do plano Enterprise e dos planos superiores.

Para acesso automatizado que pertence à organização em vez de um membro individual, os administradores podem criar Service Accounts e emitir tokens de granularidade fina com escopo limitado aos recursos da sua organização.