# Entre com sua conta do Hugging Face

Você pode usar o fluxo de OAuth / OpenID connect do HF para criar um fluxo de **"Entrar com HF"** em qualquer site ou aplicativo.

Isso permitirá que os usuários façam login no seu site ou aplicativo usando sua conta do HF, clicando em um botão semelhante a este:

![Sign in with Hugging Face](https://huggingface.co/datasets/huggingface/badges/resolve/main/sign-in-with-huggingface-xl-dark.svg)

Após clicar neste botão, seus usuários verão um modal de permissões para autorizar seu aplicativo:

![](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/oauth-accept-application.png)

## Criando um aplicativo oauth

Você pode criar seu aplicativo em suas [configurações](https://huggingface.co/settings/applications/new):

	
	

### Aplicativos OAuth pertencentes à organização

> [!WARNING]
> Este recurso faz parte dos planos Team & Enterprise.

Aplicativos OAuth também podem ser pertencentes a uma organização em vez de uma conta individual. Isso é útil para aplicativos mantidos em conjunto pela sua equipe, pois eles permanecem com a organização em vez de depender da conta de um único membro.

Administradores de organização podem criar e gerenciar aplicativos pertencentes à organização na seção **OAuth Apps** das configurações da organização (`https://huggingface.co/organizations/<your-org>/settings/applications`). Todos os administradores da organização podem editar o aplicativo, rotacionar seu client secret ou excluí-lo. A lista de aplicativos mostra qual membro criou cada aplicativo, e as alterações nos aplicativos são registradas nos [audit logs](./audit-logs#oauth-apps) da organização.

	
	

A mesma página também lista o [Token Exchange app](#token-exchange-for-organizations-rfc-8693) da organização, caso um tenha sido configurado.

Você também pode transferir um aplicativo OAuth existente que você possui para uma organização da qual você é administrador, a partir da seção **Transferir para uma organização** na página de configurações do aplicativo. A organização deve estar em um plano Team ou Enterprise. Após a transferência, o aplicativo é gerenciado por todos os administradores da organização. Seu client ID, client secret e as autorizações e tokens existentes permanecem os mesmos, portanto, seu site ou aplicativo continua funcionando sem alterações. A transferência não pode ser desfeita a partir da página de configurações.

	
	

### Aplicativos OAuth públicos (sem segredo)

Você pode criar ou usar aplicativos OAuth sem um segredo de cliente. Isso é útil para aplicativos nativos, CLIs ou outros contextos em que manter um segredo é impraticável.

- **Na criação do aplicativo**: Ao criar um novo aplicativo OAuth, você pode optar por criá-lo sem um segredo.
- **Após a criação**: Para um aplicativo existente, você pode excluir o segredo do cliente nas configurações do aplicativo. O aplicativo funcionará então como um aplicativo público.

Aplicativos públicos se autenticam usando apenas o ID do cliente (por exemplo, em fluxos de código de dispositivo ou de código de autorização com PKCE). Aplicativos que possuem um segredo ainda podem usar o segredo quando necessário (por exemplo, `Authorization: Basic` para solicitações de token).

### URIs de redirecionamento

O `redirect_uri` enviado em uma solicitação de autorização deve corresponder exatamente a um dos URIs de redirecionamento registrados no seu aplicativo.

URIs de redirecionamento de loopback são a única exceção: para URIs que usam o esquema `http` em um host de loopback (`localhost`, `127.0.0.1` ou `[::1]`), qualquer porta é aceita no momento da solicitação, desde que todos os outros componentes correspondam a uma URI registrada. Isso segue o [RFC 8252 §7.3](https://datatracker.ietf.org/doc/html/rfc8252#section-7.3) / OAuth 2.1 e permite que aplicativos nativos, CLIs e clientes MCP registrem uma URI sem porta, como `http://localhost/callback`, e depois escutem em qualquer porta efêmera que o sistema operacional lhes atribuir (por exemplo, `http://localhost:49282/callback`).

Algumas coisas a ter em mente:

- A exceção se aplica apenas ao esquema `http`. URIs de redirecionamento com `https` e esquemas personalizados (por exemplo, `myapp://callback`) sempre exigem uma correspondência exata, incluindo a porta.
- Hosts de loopback são correspondidos individualmente: uma solicitação para `http://localhost:49282/callback` não corresponde a um `http://127.0.0.1/callback` registrado. Registre ambos se o seu aplicativo puder usar qualquer um deles.
- Apenas a porta pode diferir. O caminho, a consulta e o userinfo ainda devem corresponder exatamente.

### Se você estiver hospedando em Spaces

> [!TIP]
> Se você hospedar seu aplicativo no Spaces, o fluxo será ainda mais fácil de implementar (e embutido diretamente no Gradio); consulte nosso [guia de OAuth do Spaces](https://huggingface.co/docs/hub/spaces-oauth).

### Criação automatizada de aplicativo oauth

O Hugging Face suporta CIMD, também conhecido como [Client ID Metadata Documents](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/), o que permite criar um aplicativo oauth para o seu site de forma automatizada:

- Adicione um endpoint ao seu site em `/.well-known/oauth-cimd` que retorne o seguinte JSON:

```json
{
  client_id:                  "[your website url]/.well-known/oauth-cimd",
  client_name:                "Your Website",
  redirect_uris:              ["[your website url]/oauth/callback/huggingface"],
  token_endpoint_auth_method: "none",
  logo_uri:                  "https://....", // optional
  client_uri:                 "[your website url]", // optional
}
```

- Use `"[your website url]/.well-known/oauth-cimd"` como client ID e PCKE como mecanismo de autenticação

Aplicativos nativos e clientes MCP que recebem o código de autorização em uma porta local podem listar URIs de loopback sem porta em `redirect_uris`, por exemplo, `["http://localhost/callback", "http://127.0.0.1/callback"]` — consulte [URIs de redirecionamento](#redirect-uris).

Isso é particularmente útil para ambientes efêmeros ou clientes MCP. Veja um [exemplo de implementação](https://github.com/huggingface/chat-ui/pull/1978) no Hugging Chat.

## OAuth de código de dispositivo

O fluxo de código de dispositivo permite que os usuários autorizem um aplicativo em um dispositivo (por exemplo, uma CLI) inserindo um código curto em outro dispositivo (por exemplo, um celular ou navegador). Não é necessário um URI de redirecionamento nem um navegador no dispositivo em que o aplicativo está sendo executado.

![](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/oauth-device-first-step.png)

![](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/oauth-device-second-step.png)

### Testando com um script de exemplo

Você pode testar um aplicativo OAuth de código de dispositivo com o script a seguir. Substitua `<Client ID>` pelo ID do cliente do seu aplicativo. Para **aplicativos públicos** (sem segredo), o script funciona como está. Para **aplicativos com segredo**, adicione um cabeçalho `Authorization: Basic` (Base64 de `client_id:client_secret`) tanto nas solicitações de dispositivo quanto nas de token.

```sh
#!/bin/bash
CLIENT_ID="<Client ID>"

# Step 1: Get device code
RESPONSE=$(curl -s -X POST https://huggingface.co/oauth/device \
  -d "client_id=$CLIENT_ID")

DEVICE_CODE=$(echo $RESPONSE | jq -r '.device_code')
USER_CODE=$(echo $RESPONSE | jq -r '.user_code')
VERIFICATION_URI=$(echo $RESPONSE | jq -r '.verification_uri')

echo "Device Code: $DEVICE_CODE"
echo "User Code: $USER_CODE"
echo ""
echo "Open: ${VERIFICATION_URI}"
echo "Enter the user code: $USER_CODE"
echo ""
read -p "Press Enter after authorizing..."

# Step 3: Get token
curl -X POST https://huggingface.co/oauth/token \
  -d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
  -d "device_code=$DEVICE_CODE" \
  -d "client_id=$CLIENT_ID"
```

> [!NOTE]
> Para aplicativos OAuth que possuem um segredo de cliente, inclua um cabeçalho `Authorization: Basic` (com `client_id:client_secret` codificado em Base64) tanto na solicitação do código de dispositivo quanto na solicitação do token.

## Escopos atualmente suportados

Os escopos atualmente suportados são:

- `openid`: Receba um token de ID em adição ao token de acesso.
- `profile`: Lê as informações do perfil do usuário (nome de usuário, avatar, etc.)
- `email`: Lê o endereço de e-mail do usuário.
- `read-billing`: Saber se o usuário tem um método de pagamento configurado.
- `read-memberships`: Lê as organizações às quais o usuário pertence e seu papel em cada uma delas. Isso não concede acesso às configurações ou recursos das organizações.
- `read-repos`: Lê os repositórios pessoais do usuário.
- `gated-repos`: Lê o conteúdo de repositórios públicos com acesso restrito (gated) para os quais o usuário foi autorizado. Diferentemente de `read-repos`, isso não concede acesso a repositórios privados.
- `request-gated-repos`: Solicita acesso a repositórios com restrição em nome do usuário. O perfil do usuário é compartilhado com os autores do repositório como parte da solicitação, de acordo com as configurações de restrição do repositório.
- `contribute-repos`: Cria repositórios e acessa aqueles criados por este aplicativo. Não pode acessar nenhum outro repositório, a menos que permissões adicionais sejam concedidas.
- `write-repos`: Lê e grava nos repositórios pessoais do usuário.
- `manage-repos`: Gerencia totalmente os repositórios pessoais do usuário, incluindo a criação e a exclusão deles.
- `read-collections`: Lê as coleções pessoais do usuário.
- `write-collections`: Lê e grava as coleções pessoais do usuário, incluindo a criação e a exclusão delas.
- `inference-api`: Faça solicitações de inferência para [Inference Providers](https://huggingface.co/docs/inference-providers/index) em nome do usuário.
- `read-endpoints`: Exibe os [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index) do usuário e faz solicitações de inferência a eles em nome do usuário.
- `write-endpoints`: Gerencia os Inference Endpoints do usuário, incluindo a criação e a exclusão deles. Inclui acesso `read-endpoints`.
- `jobs`: Executar [jobs](https://huggingface.co/docs/huggingface_hub/main/en/guides/jobs)
- `webhooks`: Gerenciar [webhooks](https://huggingface.co/docs/huggingface_hub/main/en/guides/webhooks)
- `write-discussions`: Abre discussões e Pull Requests em nome do usuário, bem como interage com discussões (incluindo reações, publicação/edição de comentários, fechamento de discussões, ...). Para abrir Pull Requests em repositórios privados, você precisa solicitar também o escopo `read-repos`.

Todas as outras informações estão disponíveis no [metadados OpenID](https://huggingface.co/.well-known/openid-configuration).

> [!WARNING]
> Entre em contato conosco se precisar de escopos adicionais.

## Acessando recursos da organização

Por padrão, o aplicativo oauth não precisa acessar recursos da organização.

Mas alguns escopos, como `read-repos` ou `read-billing`, também se aplicam a organizações.

O usuário pode selecionar quais organizações conceder acesso ao autorizar o aplicativo. Se você exigir acesso a uma organização específica, pode adicionar `orgIds=ORG_ID` como um parâmetro de consulta à URL de autorização do OAuth. O ID da organização está disponível no campo `orgs[].sub` da resposta de userinfo.

## Sincronizando a filiação à organização como grupos

A resposta de userinfo (`https://huggingface.co/oauth/userinfo`) inclui uma claim `groups`: os nomes das organizações às quais o usuário pertence, como um array de strings.

```json
{
  "sub": "...",
  "preferred_username": "my-username",
  "groups": ["my-org", "another-org"],
  "orgs": [ ... ]
}
```

Muitos clientes OIDC (por exemplo, Discourse, Grafana, Argo CD, Vault, Kubernetes) podem sincronizar a associação a grupos a partir de uma claim contendo um array de strings e frequentemente são configurados com uma claim `groups`. Você pode usá-la para mapear organizações do Hugging Face para papéis ou grupos no seu aplicativo. Para mais detalhes sobre cada organização (ID, papel, etc.), use o campo `orgs` em vez disso.

Algumas coisas a ter em mente:

- A afirmação `groups` é retornada apenas pelo endpoint userinfo, não no token de ID.
- Ele contém nomes de organizações, não IDs. Se uma organização for renomeada, os mapeamentos que usam seu nome antigo deixarão de corresponder.
- Os grupos de recursos não estão incluídos. Para organizações em um plano pago, os grupos de recursos e as funções do usuário estão listados em `orgs[].resourceGroups`.

## Identidade visual

Você é livre para usar seu próprio design para o botão. Abaixo estão algumas imagens SVG gentilmente fornecidas.

Confira [nossos selos](https://huggingface.co/datasets/huggingface/badges#sign-in-with-hugging-face) com explicações para integrá-los em markdown ou HTML.

[![Sign in with Hugging Face](https://huggingface.co/datasets/huggingface/badges/resolve/main/sign-in-with-huggingface-sm.svg)](https://huggingface.co/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=openid%20profile&state=STATE)
[![Sign in with Hugging Face](https://huggingface.co/datasets/huggingface/badges/resolve/main/sign-in-with-huggingface-sm-dark.svg)](https://huggingface.co/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=openid%20profile&state=STATE)

[![Sign in with Hugging Face](https://huggingface.co/datasets/huggingface/badges/resolve/main/sign-in-with-huggingface-md.svg)](https://huggingface.co/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=openid%20profile&state=STATE)
[![Sign in with Hugging Face](https://huggingface.co/datasets/huggingface/badges/resolve/main/sign-in-with-huggingface-md-dark.svg)](https://huggingface.co/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=openid%20profile&state=STATE)

[![Sign in with Hugging Face](https://huggingface.co/datasets/huggingface/badges/resolve/main/sign-in-with-huggingface-lg.svg)](https://huggingface.co/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=openid%20profile&state=STATE)
[![Sign in with Hugging Face](https://huggingface.co/datasets/huggingface/badges/resolve/main/sign-in-with-huggingface-lg-dark.svg)](https://huggingface.co/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=openid%20profile&state=STATE)

[![Sign in with Hugging Face](https://huggingface.co/datasets/huggingface/badges/resolve/main/sign-in-with-huggingface-xl.svg)](https://huggingface.co/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=openid%20profile&state=STATE)
[![Sign in with Hugging Face](https://huggingface.co/datasets/huggingface/badges/resolve/main/sign-in-with-huggingface-xl-dark.svg)](https://huggingface.co/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=openid%20profile&state=STATE)

## Troca de Token para Organizações (RFC 8693)

> [!WARNING]
> Este recurso faz parte do plano Enterprise.

O Token Exchange permite que as organizações emitam programaticamente tokens de acesso para seus membros, sem exigir o consentimento interativo do usuário. Isso é particularmente útil para a construção de ferramentas internas, pipelines de automação e integrações corporativas que precisam acessar recursos do Hugging Face em nome dos membros da organização.

> [!TIP]
> Se você precisa apenas de autenticação sem chave a partir de um workflow de CI/CD (GitHub Actions, GitLab CI, CircleCI, …) — sem emissão de tokens por membro — consulte [Trusted Publishers](./trusted-publishers), que também usa `/oauth/token`, mas utiliza um `id_token` OIDC emitido pelo seu provedor de CI como token de assunto (não requer plano Enterprise, nem credenciais de cliente).

Este recurso implementa o [RFC 8693 - OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693.html), um protocolo padrão para cenários de troca de tokens.

### Casos de uso

O Token Exchange foi projetado para cenários em que sua organização precisa:

- **Construir plataformas internas**: Crie painéis ou portais que acessem recursos do Hugging Face em nome dos membros da sua equipe, sem exigir que cada usuário autentique manualmente.
- **Automatize pipelines de CI/CD**: Emita tokens de curta duração e com escopo limitado para fluxos de trabalho automatizados que precisam enviar modelos ou conjuntos de dados para repositórios da organização.
- **Integrar com sistemas de identidade corporativos**: Conecte seu provedor de identidade existente ao Hugging Face emitindo tokens com base no seu diretório interno de usuários.
- **Implementar controles de acesso personalizados**: Crie um middleware que emita tokens com escopos específicos com base nas políticas internas da sua organização.

### Como funciona

1. Sua organização possui um aplicativo OAuth vinculado à sua organização com o privilégio `token-exchange`.
2. Seu serviço de backend autentica-se neste aplicativo OAuth usando credenciais de cliente.
3. Seu serviço solicita um token de acesso para um membro específico da organização (identificado por e-mail).
4. O Hugging Face verifica se o usuário é membro da sua organização e emite um token com escopo definido.
5. O token emitido pode acessar apenas recursos dentro do escopo da sua organização.

### Pré-requisitos

Para usar o Token Exchange, você precisa de um aplicativo OAuth vinculado a uma organização com o privilégio `token-exchange`. Entre em contato com o suporte da Hugging Face para configurar um aplicativo OAuth elegível para a sua organização.

Uma vez configurado, você receberá:
- Um **ID do cliente** (por exemplo, `a1b2c3d4-e5f6-7890-abcd-ef1234567890`)
- Um **Client Secret** (mantenha-o seguro!)

> [!WARNING]
> Administradores de organização podem gerenciar o aplicativo OAuth após a criação, incluindo a atualização do segredo do cliente e a configuração da duração do token. O aplicativo é listado na seção **OAuth Apps** das configurações da sua organização, e as alterações nele são registradas nos [logs de auditoria](./audit-logs#oauth-apps) da organização.

### Autenticação

O Token Exchange usa a autenticação básica HTTP com as credenciais do seu aplicativo OAuth. Crie o cabeçalho de autorização codificando em Base64 o seu `client_id:client_secret`:

```bash
# Create the authorization header
export CLIENT_ID="your-client-id"
export CLIENT_SECRET="your-client-secret"
export AUTH_HEADER=$(echo -n "${CLIENT_ID}:${CLIENT_SECRET}" | base64)
```

### Emitindo tokens por e-mail

Para emitir um token de acesso para um membro da organização usando seu endereço de e-mail:

```bash
curl -X POST "https://huggingface.co/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic ${AUTH_HEADER}" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "subject_token=user@yourorg.com" \
  -d "subject_token_type=urn:huggingface:token-type:user-email"
```

### Resposta

Uma solicitação bem-sucedida retorna um token de acesso:

```json
{
  "access_token": "hf_oauth_...",
  "token_type": "bearer",
  "expires_in": 28800,
  "scope": "openid profile email read-repos",
  "id_token": "eyJhbGciOiJS...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}
```

O campo `id_token` é incluído quando o escopo `openid` é solicitado.

Em seguida, você pode usar esse token para fazer solicitações de API em nome do usuário:

```bash
curl "https://huggingface.co/api/whoami-v2" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"
```

### Controle de escopo

Por padrão, os tokens emitidos herdam todos os escopos configurados no aplicativo OAuth. Você pode solicitar escopos específicos adicionando o parâmetro `scope`. Consulte [Escopos atualmente suportados](#currently-supported-scopes) para os valores disponíveis.

As permissões efetivas do token são limitadas tanto pelo escopo solicitado quanto pelo papel do usuário dentro da organização.

```bash
curl -X POST "https://huggingface.co/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic ${AUTH_HEADER}" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "subject_token=user@yourorg.com" \
  -d "subject_token_type=urn:huggingface:token-type:user-email" \
  -d "scope=openid profile"
```

> [!TIP]
> Siga o princípio do menor privilégio: solicite apenas os escopos que seu aplicativo realmente precisa.

### Considerações de segurança

Tokens emitidos via Token Exchange possuem restrições de segurança integradas:

- **Escopo da organização**: Os tokens só podem acessar recursos dentro da sua organização (modelos, conjuntos de dados, Spaces e coleções pertencentes à organização). Fora da organização, o acesso é somente leitura e limitado a: coleções públicas de qualquer usuário ou organização e repositórios públicos com controle de acesso aos quais o usuário tenha sido individualmente autorizado.
- **Sem acesso pessoal**: Os tokens não podem acessar os repositórios privados pessoais do usuário nem repositórios privados de outras organizações.
- **Curta duração**: Os tokens expiram após 8 horas por padrão. Os administradores da organização podem configurar a duração do token (até 30 dias) nas configurações do aplicativo OAuth. Nenhum token de atualização é fornecido.
- **Auditável**: Todas as trocas de tokens são registradas e visíveis nos [logs de auditoria](./audit-logs) da sua organização.

> [!WARNING]
> Proteja com cuidado as credenciais do seu aplicativo OAuth. Qualquer pessoa com acesso ao seu segredo de cliente pode emitir tokens para qualquer membro da sua organização.

### Respostas de erro

| Erro | Descrição |
|-------|-------------|
| `invalid_client` | O cliente não está autorizado a usar a troca de token, ou o aplicativo não está vinculado a uma organização |
| `invalid_grant` | Usuário não encontrado na organização vinculada |
| `invalid_scope` | O escopo solicitado não é válido |

### Referência

**Tipo de concessão:**
```
urn:ietf:params:oauth:grant-type:token-exchange
```

**Parâmetro da requisição (`subject_token_type`):**

| Valor | Descrição |
|-------|-------------|
| `urn:huggingface:token-type:user-email` | Identifique o usuário pelo endereço de e-mail |

**Campo de resposta (`issued_token_type`):**

| Valor | Descrição |
|-------|-------------|
| `urn:ietf:params:oauth:token-type:access_token` | Indica que um token de acesso foi emitido |

**Documentação relacionada:**
- [RFC 8693 - Exchange de Token do OAuth 2.0](https://www.rfc-editor.org/rfc/rfc8693.html)
- [Registros de auditoria](./audit-logs)

