> ## Documentation Index
> Fetch the complete documentation index at: https://docs.norbaas.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Conexão com OAuth 2.0

## Autorização

Para iniciar o fluxo de autorização, você precisa redirecionar o usuário para a URL de autorização. Ela se parece com isto:

```
https://norbaas.com.br/oauth2/authorize?
  response_type=code
  &client_id=CLIENT_ID
  &redirect_uri=https%3A%2F%2Fexample.com%2Fcallback
  &scope=openid%20email
```

Os parâmetros são aqueles descritos na [especificação do OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). Os mais importantes são:

<ParamField path="response_type=code" type="string" required>
  Indica que você deseja usar o fluxo de autorização por código. É o mais comum e o único suportado pelo Norbaas.
</ParamField>

<ParamField path="client_id" type="string" required>
  O ID do Cliente que você recebeu ao criar o cliente OAuth 2.0.
</ParamField>

<ParamField path="redirect_uri" type="string" required>
  A URL para a qual o usuário será redirecionado após conceder acesso aos seus dados. Certifique-se de que ela foi declarada ao criar o cliente OAuth2.
</ParamField>

<ParamField path="scope" type="string" required>
  Uma lista de escopos separados por espaço que você deseja solicitar. Certifique-se de que eles fazem parte dos escopos declarados ao criar o cliente OAuth2.
</ParamField>

Se você redirecionar o usuário para essa URL, ele verá uma página solicitando permissão para acessar seus dados, de acordo com os escopos que você solicitou.

<img src="https://mintcdn.com/norbaas/5OPQggdmVnQLu7D4/assets/integrate/oauth2/connect.png?fit=max&auto=format&n=5OPQggdmVnQLu7D4&q=85&s=fe3482318b3fad75b806c8ee16e296b9" width="1920" height="1080" data-path="assets/integrate/oauth2/connect.png" />

Se eles permitirem, serão redirecionados para o seu `redirect_uri` com um parâmetro `code` na query string. Esse código é de uso único e pode ser trocado por um token de acesso.

#### Trocar o código por um token

Uma vez que você tenha o código de autorização, você pode trocá-lo por um token de acesso. Para isso, é necessário fazer uma requisição `POST` para o endpoint de token. Essa chamada precisa ser autenticada com o Client ID e o Client Secret que você obteve ao criar o cliente OAuth2.

Aqui está um exemplo usando cURL:

```bash theme={null}
curl -X POST https://api.norbaas.sh/v1/oauth2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&code=AUTHORIZATION_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=https://example.com/callback'
```

Você deverá receber a seguinte resposta:

```json theme={null}
{
  "token_type": "Bearer",
  "access_token": "norbaas_at_XXX",
  "expires_in": 864000,
  "refresh_token": "norbaas_rt_XXX",
  "scope": "openid email",
  "id_token": "ID_TOKEN"
}
```

O `access_token` permitirá que você faça requisições autenticadas à API em nome do usuário. O `refresh_token` é um token de longa duração que pode ser usado para obter novos access tokens quando o atual expirar. O `id_token` é um token JWT assinado contendo informações sobre o usuário, conforme a [especificação do OpenID Connect.](https://openid.net/specs/openid-connect-core-1_0.html#IDToken).

#### Tokens de Acesso de Usuário vs Organização

Nós damos suporte ao conceito de tokens de acesso em nível de organização. Ao contrário dos tokens de acesso padrão, esses tokens não estão vinculados a um usuário, mas sim a uma organização. Eles podem ser usados para fazer requisições operando exclusivamente nos dados de uma organização específica, melhorando a privacidade e a segurança.

Para solicitar um token de acesso de organização, é necessário adicionar o parâmetro `sub_type=organization` à URL de autorização:

```
https://norbaas.com.br/oauth2/authorize?response_type=code&client_id=norbaas_ci_j3X95_MgfdSCeCd2qkFnUw&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&scope=openid%20email&sub_type=organization
```

Neste ponto, o usuário será solicitado a selecionar uma de suas organizações antes de permitir o acesso aos seus dados.

O restante do fluxo permanece inalterado. O token de acesso que você receber estará vinculado à organização selecionada.

Tenha em mente que alguns endpoints podem não oferecer suporte a tokens de acesso de organização.
Normalmente, endpoints específicos do usuário como `/v1/users/benefit` não funcionarão com tokens de acesso de organização.

#### Clientes Públicos

Clientes públicos são aqueles em que o Client Secret (segredo do cliente) não pode ser mantido em segurança, pois estaria acessível ao usuário final. Esse é o caso de aplicações SPA, aplicativos móveis ou qualquer cliente executado no dispositivo do usuário.

Nesse caso, e **somente se o cliente estiver configurado como um Cliente Público**, a requisição para o endpoint de token não exigirá o parâmetro `client_secret`. No entanto, o método [PKCE](https://oauth.net/2/pkce/) será necessário para maximizar a segurança.

### Fazer requisições autenticadas

Uma vez que você tenha um token de acesso, seja a partir de um Personal Access Token ou do fluxo OpenID Connect, você pode fazer requisições autenticadas para a API. Aqui está um exemplo simples com cURL:

```bash theme={null}
curl -X GET https://api.norbaas.sh/v1/oauth2/userinfo \
  -H 'Authorization: Bearer norbaas_at_XXX'
```