Skip to main content

​
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. Os mais importantes são:
​
response_type=code
string
required
Indica que você deseja usar o fluxo de autorização por código. É o mais comum e o único suportado pelo Norbaas.
​
client_id
string
required
O ID do Cliente que você recebeu ao criar o cliente OAuth 2.0.
​
redirect_uri
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.
​
scope
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.
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. 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: 
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: 
{
  "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..

​
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 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: 
curl -X GET https://api.norbaas.sh/v1/oauth2/userinfo \
  -H 'Authorization: Bearer norbaas_at_XXX'