Tokens de acesso do usuário

O que são tokens de acesso do usuário?

Os User Access Tokens são a forma preferencial de autenticar um aplicativo ou notebook nos serviços do Hugging Face. Você pode gerenciar seus tokens de acesso em suas configurações.

Os tokens de acesso permitem que aplicativos e notebooks executem ações específicas definidas pelo escopo dos papéis mostrados a seguir:

• fine-grained: tokens com esse papel podem ser usados para fornecer acesso granular a recursos específicos, como um modelo específico ou modelos em uma organização específica. Esse tipo de token é útil em ambientes de produção, pois você pode usar seu próprio token sem compartilhar o acesso a todos os seus recursos.

• read: tokens com esse papel só podem ser usados para fornecer acesso de leitura a repositórios que você poderia ler. Isso inclui repositórios públicos e privados que você, ou uma organização da qual você é membro, possui. Use esse papel se você precisar apenas ler conteúdo do Hugging Face Hub (por exemplo, ao baixar modelos privados ou executar inferência).

• write: tokens com esse papel concedem, adicionalmente, acesso de escrita aos repositórios para os quais você tem acesso de escrita. Use esse token se precisar criar ou enviar conteúdo para um repositório (por exemplo, ao treinar um modelo ou modificar um cartão de modelo).

Se você for membro de uma organização com papel de leitura/escrita/administração, seus Tokens de Acesso do Usuário poderão ler/escrever os recursos de acordo com a permissão do token (leitura/escrita) e a filiação à organização (leitura/escrita/administração).

Como gerenciar tokens de acesso do usuário?

Para criar um token de acesso, acesse suas configurações e clique na aba Tokens de acesso. Clique no botão Novo token para criar um novo Token de Acesso do Usuário.

Selecione um papel e um nome para o seu token e voilà - você está pronto para começar!

Você pode excluir e atualizar os Tokens de Acesso do Usuário clicando no botão Manage.

Como usar tokens de acesso do usuário?

Existem diversas maneiras de usar um User Access Token para acessar o Hugging Face Hub, oferecendo a flexibilidade necessária para criar aplicativos incríveis com base nele.

Os tokens de acesso do usuário podem ser:

• usado no lugar de uma senha para acessar o Hugging Face Hub com git ou com autenticação básica.
• passado como um bearer token ao chamar os Inference Providers.
• usado nas bibliotecas Python do Hugging Face, como transformers ou datasets:

from transformers import AutoModel

access_token = "hf_..."

model = AutoModel.from_pretrained("private/model", token=access_token)

Tente não vazar seu token! Embora você possa sempre rotacioná-lo, qualquer pessoa poderá ler ou escrever em seus repositórios privados no meio tempo, o que é 💩 Veja Revogando um token vazado se um token tiver sido exposto.

Boas práticas

Recomendamos que você crie um token de acesso por aplicativo ou uso. Por exemplo, você pode ter um token separado para:

• Um computador local.
• Um notebook do Colab.
• Um servidor de inferência personalizado incrível.

Dessa forma, você pode invalidar um token sem impactar seus outros usos.

Também recomendamos o uso apenas de tokens de granularidade fina para uso em produção. O impacto, em caso de vazamento, será reduzido, e eles podem ser compartilhados entre sua organização sem impactar sua conta.

Por exemplo, se o seu aplicativo de produção precisar de acesso de leitura a um modelo restrito, um membro da sua organização pode solicitar acesso ao modelo e, em seguida, criar um token de granularidade fina com acesso de leitura a esse modelo. Esse token pode então ser usado no seu aplicativo de produção sem conceder a ele acesso a todos os seus modelos privados.

Para pipelines de CI/CD

Se você precisa apenas de acesso a partir de um fluxo de CI/CD (GitHub Actions, GitLab CI, CircleCI, …), pode evitar armazenar um token de acesso como um segredo de CI por completo. Consulte Trusted Publishers, que troca o token de identidade OpenID Connect (OIDC) do seu provedor de CI por um token de Hub de curta duração no início de cada execução — seja com escopo de repositório (para publicar modelos, conjuntos de dados, Spaces ou kernels, ou para obtê-los somente leitura) ou com escopo de usuário (para ler repositórios restritos aos quais você tem acesso e obter os limites de taxa da sua conta).

Para organizações Enterprise

Se a sua organização precisa emitir tokens programaticamente para os membros sem exigir que cada usuário crie o próprio token, consulte OAuth Token Exchange. Este recurso do plano Enterprise é ideal para construir plataformas internas, pipelines de CI/CD ou integrações personalizadas que precisam acessar recursos do Hugging Face em nome dos membros da organização.

Revogando um token vazado

Se um dos seus próprios tokens tiver vazado, exclua-o ou atualize-o na aba Access Tokens das suas configurações.

Se você encontrou um token de acesso do Hugging Face de outra pessoa, pode invalidá-lo com o endpoint POST /api/credentials/revoke. Você não precisa de nenhum direito sobre a conta ou organização que possui o token.

# LEAKED_HF_TOKEN should contain the raw token value to revoke
curl -X POST "https://huggingface.co/api/credentials/revoke" \
  -H "Content-Type: application/json" \
  -d "{\"credentials\": [\"${LEAKED_HF_TOKEN}\"]}"

Você pode passar vários valores de token no array credentials em uma única chamada, o que é conveniente para pipelines de varredura de segredos que relatam resultados em lotes.

Todo token enviado que corresponda a um existente é invalidado imediatamente e deixa de funcionar em todos os lugares — diferente da revogação em nível de organização, que apenas corta o acesso do token a uma única organização. O proprietário do token é notificado por e-mail e precisa criar um novo token para restaurar o acesso.

O endpoint sempre responde com 202 Accepted, independentemente de algum dos tokens enviados existir ou não, portanto sua resposta não pode ser usada para verificar se um token é válido. Enviar o mesmo token novamente é inofensivo: chamadas repetidas não fazem nada e o proprietário é notificado apenas uma vez.

Para evitar a exposição de valores de tokens no histórico do shell ou em logs, passe-os por meio de variáveis de ambiente ou arquivos e evite colar tokens brutos diretamente nas linhas de comando.

Tokens em organizações com políticas de gerenciamento de tokens

Organizações com planos Team e Enterprise podem aplicar políticas de token que afetam o funcionamento dos seus tokens ao acessar os recursos dessa organização.

Quando seu token requer aprovação (organizações Team & Enterprise)

Ao criar um token de granularidade fina com escopo para uma organização que exige aprovação de administrador, o token entra automaticamente no estado Pending. Ele não pode acessar os recursos dessa organização até que um administrador o aprove. Você receberá uma notificação por e-mail quando seu token for aprovado ou negado.

Você pode verificar o status na sua página de lista de tokens. Um token pendente exibe um ícone de ampulheta laranja ao lado do selo de permissões, e um token negado ou revogado exibe um ícone de exclamação vermelho. Um banner de erro vermelho também aparece na página de edição do token se o seu token foi negado ou revogado.

Se você é administrador da organização, os tokens de granularidade fina que você criar com escopo definido para essa organização são aprovados automaticamente — nenhuma etapa de revisão é necessária.

Quando seu token é negado (organizações Team & Enterprise)

Se o seu token for negado, você receberá uma notificação por e-mail. O token permanece na sua conta e ainda pode ser usado para recursos fora da organização. Um token negado pode ser aprovado posteriormente por um administrador, restaurando o acesso sem que você precise criar um novo token.

Ao tentar usar um token negado contra recursos da organização, você receberá um erro 403.

Quando seu token é revogado (organizações Enterprise)

A revogação é permanente. Diferentemente da negação, um token revogado não pode ser reativado. Se o seu token tiver sido revogado, você deve excluí-lo e criar um novo. Se a organização exigir aprovação do administrador, o novo token começará em um estado pendente.

Ao tentar usar um token revogado contra recursos da organização, você receberá 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.”

A revogação afeta apenas a organização que a executou. O token continua funcionando normalmente para todos os outros recursos aos quais ele está vinculado.

Quando sua organização permite apenas tokens de granularidade fina (organizações Team & Enterprise)

Se a sua organização definiu uma política que exige tokens de granularidade fina, tokens de leitura/escrita serão rejeitados com um erro 403 quando usados contra os recursos dessa organização.