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

# Visão geral da autenticação

O Localpayment utiliza autenticação por token Bearer OAuth 2.0 para proteger o acesso à API. Todas as requisições à API exigem um token de acesso válido incluído no cabeçalho `Authorization`. Este guia fornece uma visão geral dos conceitos de autenticação e dos requisitos de segurança.

A autenticação segura é fundamental para a integração de APIs. A autenticação baseada em tokens da Localpayment garante que apenas solicitações autorizadas possam acessar os dados da sua conta e processar transações.

> [card] OAuth 2.0
>
> Autenticação de token Bearer padrão do setor

> [card] Tokens de curta duração
>
> Tokens de acesso de 60 minutos para maior segurança.

***

## Requisitos de segurança

> [!WARNING]
>
> **Requisitos críticos de segurança**
>
> Siga estas práticas para garantir uma integração segura da API.

> [card] Criptografia HTTPS
>
> Toda a comunicação via API deve usar HTTPS para proteger os dados em trânsito.

> [card] Somente no lado do servidor
>
> As solicitações de API devem ser originadas somente de ambientes de servidor seguros.

> [card] Lista branca de IPs
>
> Configure a lista de permissões de IP no painel de controle para autorizar chamadas de API.

> [card] Armazenamento seguro de credenciais
>
> Utilize variáveis de ambiente ou sistemas de gerenciamento de segredos.

***

## Endpoints de autenticação

Gerencie sua autenticação de API usando estes endpoints dedicados:

> [card] [Obtenha o token de acesso.](https://docs.localpayment.com/pt-br/reference/get-token.md)
>
> Obtenha novos tokens de acesso e atualização usando suas credenciais de API.

> [card] [Atualizar token de acesso](https://docs.localpayment.com/pt-br/reference/refresh-token.md)
>
> Obtenha novos tokens de acesso usando seu token de atualização sem precisar se autenticar novamente.

### Exemplo rápido

**Gerar token:**

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/token/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "username": "user@example.com",
  "password": "<PASSWORD>"
}
'
```

**Usar token:**

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/validation/document \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "country": "ARG",
  "document": {
    "id": "1791234561009",
    "type": "RUC"
  }
}
'
```

***

## Expiração do token

O Localpayment utiliza tokens de curta duração para maior segurança:

> [card] Token de acesso
>
> **60 minutos**\\
>
> Usado para requisições de API\\
>
> Curta duração por segurança

> [card] Token de atualização
>
> **120 minutos**\\
>
> Usado para obter novos tokens de acesso\\
>
> Longa duração por conveniência

### Ciclo de vida do token

1. **Obtenha os tokens**: solicite um par de token de acesso e token de atualização com [Obter token de acesso](https://docs.localpayment.com/pt-br/reference/get-token.md).
2. **Reutilize o token de acesso**: envie o mesmo token de acesso em todas as requisições enquanto ele for válido.
3. **Renove ao expirar**: quando o token de acesso expirar ou você receber uma resposta 401 Não autorizado, solicite um novo par com Obter token de acesso.
4. **Substitua o par armazenado**: armazene os dois novos tokens e descarte os anteriores.

> [!TIP]
>
> **Uso do endpoint de atualização**
>
> O endpoint [Atualizar token de acesso](https://docs.localpayment.com/pt-br/reference/refresh-token.md) continua disponível se a sua integração já o utiliza. Cada atualização bem-sucedida retorna um novo par de tokens, e o token de atualização que você enviou deixa de funcionar.
>
> Uma nova requisição a Obter token de acesso também invalida os tokens de atualização emitidos antes dela para o mesmo usuário e integração.

***

## Boas práticas de gerenciamento de tokens

> [card] Um par de tokens por integração
>
> Mantenha um único par de tokens por usuário e integração, compartilhado entre todos os seus processos e workers.

> [card] Substitua o par completo
>
> Após cada solicitação ou atualização de token, armazene o novo token de acesso e o novo token de atualização.

> [card] Evite logins em paralelo
>
> Não solicite tokens em paralelo com o mesmo usuário. Cada nova solicitação de token invalida os tokens de atualização anteriores.

> [card] Não repita uma atualização com falha
>
> Se uma atualização retornar 401, solicite um novo token com Obter token de acesso em vez de repetir o mesmo token de atualização.

***

## Tratamento de erros

> [card] 401 Não autorizado
>
> **Token inválido ou expirado** \\
>
> Solução: solicite um novo token com [Obter token de acesso](https://docs.localpayment.com/pt-br/reference/get-token.md). Se uma atualização retornar este erro, não repita o mesmo token de atualização.

> [card] 401 Não autorizado
>
> **IP não incluído na lista de permissões**\\
>
> Obter token de acesso retorna "Invalid IP for user. Please validate that 203.0.113.10 is whitelisted in your account settings."\\
>
> Solução: adicione o IP do seu servidor à [lista de permissões](https://docs.localpayment.com/pt-br/docs/dashboard-whitelist-your-ips.md) no painel.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.