# Autenticação

Para fazer um pagamento usando qualquer uma das operações da API do Ripple Payments, você precisa de um *token de acesso* válido.

Esse token de acesso é exigido por todas as operações da API do Ripple Payments (exceto a própria operação de autenticação). Você precisa incluir um token de acesso válido no cabeçalho `Authorization` de cada requisição.

Ripple Payments oferece um modelo seguro de autenticação e autorização, fornecendo tokens de acesso com escopo definido para um conjunto de credenciais.

A operação de autenticação retorna um token de acesso no campo de resposta `access_token`. Você precisa incluir o seu `client_id` e o seu `client_secret` no corpo JSON para obter um token de acesso válido.

Observação
O comprimento do token de acesso não é fixo e pode variar. Evite validar tokens pelo número de caracteres.

## Gerar client ID e client secret

Você precisa do seu *client ID* e do seu *client secret* para obter um token de acesso.

Se você ainda não tem o seu client ID e client secret, faça o seguinte:

1. Faça login no [Ripple Payments](https://home.ripple.com).
2. No canto superior direito da página, clique no ícone de engrenagem **Configurações**.
3. Em **Integração**, selecione **Credenciais de API**.
4. No canto superior direito da página, selecione o ambiente de acesso na lista suspensa. Por exemplo, para provisionar credenciais do ambiente UAT, selecione **UAT** na lista suspensa.
5. No canto superior direito da página, clique em **Nova credencial**.
6. No campo **Nome da credencial**, informe um nome para a credencial.
7. Clique em **Salvar e gerar chave**.


Aviso
O *client secret* é exibido apenas uma vez, no momento em que você cria novas credenciais.

Não é possível recuperar o secret depois de sair desta página.

Copie e armazene o client secret com segurança e compartilhe-o apenas com pessoas autorizadas, conforme a política de segurança da sua organização.

Agora você pode usar o client ID e o client secret para gerar tokens de acesso pela operação de autenticação.

Recomendamos rotacionar as suas credenciais de API em intervalos regulares, conforme a política de segurança da sua organização.

## Obter um token de acesso

Assim que tiver o seu *client ID* e o seu *client secret*, siga estas etapas para obter um token de acesso que você possa usar nas chamadas da API do Ripple Payments:

### Determinar o ambiente desejado

A primeira etapa para obter um token de acesso é determinar o ambiente que você quer acessar.

A tabela a seguir descreve as diferenças de tipos de parceiros e de moeda nos ambientes que dão acesso à API do Ripple Payments. Anote a string de ambiente do ambiente que você quer acessar.

| **Ambiente** | **URL da requisição** | **String de ambiente** | **Parceiros** | **Moeda** |
|  --- | --- | --- | --- | --- |
| **UAT** | `https://api.test.ripple.com/v2/oauth/token` | `uat` | Simulado | Simulado |
| **Production** | `https://api.ripple.com/v2/oauth/token` | `prod` | Real | Real |


### Solicitar o token de acesso

O formato de uma requisição de autenticação é o seguinte:

```json
POST https://api.ripple.com/v2/oauth/token
Content-Type: application/json
{
   "grant_type":"client_credentials",
   "client_id":"{YOUR_CLIENT_ID}",
   "client_secret":"{YOUR_CLIENT_SECRET}",
   "audience": "urn:ripplexcurrent-{ENVIRONMENT_STRING}:{YOUR_TENANT_ID}"
}
```

Os valores esperados são os seguintes:

| **Chave** | **Valor** | **Descrição** |
|  --- | --- | --- |
| `grant_type` | `client_credentials` | Define o grant-type desta requisição de client credentials. |
| `client_id` | *{YOUR_CLIENT_ID}* | Faça login no Payments Direct UI para recuperar o seu client ID do Ripple Payments. |
| `client_secret` | *{YOUR_CLIENT_SECRET}* | Recupere o client secret do Ripple Payments que foi gerado quando você criou o conjunto atual de credenciais no Payments Direct UI. |
| `audience` | `urn:ripplexcurrent- `*{ENVIRONMENT_STRING}*`:`*{YOUR_TENANT_ID}* | O valor do campo `audience` é baseado na sintaxe [URN](https://en.wikipedia.org/wiki/Uniform_Resource_Name). O segundo componente do URN precisa se referir ao ambiente que você quer acessar. Os engenheiros de integração da Ripple fornecem o seu tenant ID (o terceiro componente do URN) durante o treinamento. |


Exemplos:

**Exemplo de requisição (sucesso no ambiente de produção)** – uma requisição bem-sucedida a um ambiente de produção pode ser parecida com o exemplo a seguir:

```json
POST https://api.ripple.com/v2/oauth/token
Content-Type: application/json
{
    "grant_type": "client_credentials",
    "client_id": "{YOUR_CLIENT_ID}",
    "client_secret": "{YOUR_CLIENT_SECRET}",
    "audience": "urn:ripplexcurrent-prod:{YOUR_TENANT_ID}"
}
```

**Exemplo de resposta (sucesso no ambiente de produção)** – uma requisição bem-sucedida retorna uma resposta parecida com o exemplo a seguir:

```json
{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "keys:read keys:write payments:create quotes:create identities:create audit:read"
}
```

### Testar o token de acesso

Use o endpoint `/oauth/token/test` para verificar a validade do seu token de acesso em um ambiente Ripple específico e descobrir quanto tempo resta até ele expirar.

#### Exemplo de teste de token

Este exemplo demonstra como usar o endpoint `/oauth/token/test` para testar um token de acesso.

Aqui, aplicamos o token de acesso `eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ` ao cabeçalho `Authorization: Bearer`.

```json
GET https://api.ripple.com/v2/oauth/token/test
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ
```

Atenção : os tokens de acesso são confidenciais
Lembre-se de substituir o token de exemplo `eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ` pelo seu token de acesso real e nunca compartilhe o seu token de acesso publicamente.

#### Exemplo de resposta do teste de token

A resposta é um objeto JSON com as seguintes propriedades:

* `message` : indica o status do token de acesso.
* `seconds_to_expiry` : representa o número de segundos restantes até o token de acesso expirar.


```json
{
"message": "token_ok",
"seconds_to_expiry": 3600
}
```

## Autorizar operações da API do Ripple Payments com o token de acesso

Ripple Payments usa [Bearer Token Authorization](https://tools.ietf.org/html/rfc6750) em todas as operações (exceto a própria operação de autenticação). Para fazer requisições bem-sucedidas à API do Ripple Payments, inclua um token de acesso válido no cabeçalho `Authorization` de cada requisição, no seguinte formato:

```json
Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ
```

Para usar isso em uma requisição de API, adicione o valor do campo `access_token` ao cabeçalho **Authorization** em todas as operações da API do Ripple Payments (exceto a própria operação de autenticação). Lembre-se de acrescentar `Bearer` (incluindo um espaço) antes do token de acesso.

Por exemplo:

```json
GET https://api.ripple.com/v2/payments/{YOUR_PAYMENT_ID}
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ
```

## Erros de autenticação

Se uma requisição de token falhar, o corpo da resposta usa o formato no estilo OAuth, com os campos `error` e `error_description`, em vez do formato padrão de erro de pagamento. A tabela a seguir lista as respostas que você pode receber:

| Status HTTP | `error` | Significado |
|  --- | --- | --- |
| 400 | `invalid_request` | Falta um parâmetro obrigatório ou ele está malformado. Corrija a requisição e reenvie. |
| 401 | `access_denied` | As credenciais de cliente informadas são inválidas. Confira o seu `client_id` e o seu `client_secret`. |
| 403 | `access_denied` | O serviço não está habilitado para o domínio solicitado. Confira o valor de `audience`. |
| 403 | `unauthorized_client` | O cliente não está autorizado a solicitar um token. Entre em contato com o suporte técnico da Ripple. |


Baseie o seu tratamento de erros no código de status HTTP, e não na string `error`, e trate qualquer `403` como uma falha de autorização que não deve ter nova tentativa. Tentar novamente com as mesmas credenciais produz o mesmo resultado.

## Expiração e cache do token de acesso

Os tokens de acesso são válidos por 1 hora. Depois que você obtém um novo token, ele fica em cache por um tempo limitado. Para evitar problemas causados por cache duplo, não armazene o token em cache no cliente. Se você armazenar o token em cache, precisa limpar o cache dentro do período especificado pelo campo `expires_in` (conforme a claim `exp` do JWT) no corpo da resposta.

## Lista de IPs permitidos

Payments Direct não oferece suporte a listas de IPs permitidos. A API do Payments Direct foi projetada para acesso aberto pela internet pública, protegida por credenciais de cliente OAuth2 e autorização por Bearer token, e não por restrições de IP em nível de rede.