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

# iGps API Authentication: Obtain and Use Bearer Tokens

> Learn how to exchange your client_id and client_secret for a short-lived Bearer token and authorize all subsequent iGps API requests.

A iGps usa autenticação com token Bearer. Antes de chamar qualquer endpoint da API, você deve trocar seu `client_id` e `client_secret` por um token de acesso de curta duração. Esse token é então passado no cabeçalho `Authorization` de todas as requisições subsequentes.

## Obtenha Suas Credenciais

As credenciais são emitidas pela iGps para cada integração. Cada conjunto de credenciais identifica sua aplicação de forma única e controla o acesso à API.

<Note>
  Entre em contato com o suporte iGps para receber seu `client_id` e `client_secret`.
</Note>

## Solicite um Token de Acesso

Envie uma requisição `POST` para `/api/v1/auth/token` com suas credenciais no corpo JSON:

```bash theme={null}
curl -X POST https://api.igps.com.br/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'
```

Uma resposta bem-sucedida se parece com isto:

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

| Campo          | Descrição                                                                         |
| -------------- | --------------------------------------------------------------------------------- |
| `access_token` | O token a ser incluído no cabeçalho `Authorization` de todas as requisições à API |
| `token_type`   | Sempre `Bearer`. Use este prefixo ao definir o cabeçalho                          |
| `expires_in`   | Segundos até o token expirar (`3600` = 1 hora)                                    |

## Utilize o Token nas Requisições

Inclua o token de acesso em toda requisição à API usando o cabeçalho `Authorization`:

```bash theme={null}
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

Aqui estáum exemplo completo consultando posições de veículos com uma requisição autenticada:

```bash theme={null}
curl -X POST https://api.igps.com.br/api/v1/veiculos/posicoes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"chassis": ["VIN00000000000001"]}'
```

## Expiração e Renovação do Token

Os tokens são válidos por **3600 segundos (1 hora)** a partir do momento da emissão. Uma vez expirado, qualquer requisição feita com o token antigo retornará um erro `401 Unauthorized`. Sua integração deve detectar isso e solicitar um novo token automaticamente.

A classe Python a seguir demonstra um padrão de boas práticas para gerenciar o ciclo de vida do token. Ela renova o token de forma transparente 60 segundos antes da expiração, para que suas requisições nunca falhem devido a uma credencial expirada:

```python theme={null}
import time
import requests

class IgpsClient:
    def __init__(self, client_id, client_secret):
        self.client_id = client_id
        self.client_secret = client_secret
        self._token = None
        self._token_expiry = 0

    def get_token(self):
        if time.time() < self._token_expiry - 60:
            return self._token
        resp = requests.post(
            "https://api.igps.com.br/api/v1/auth/token",
            json={"client_id": self.client_id, "client_secret": self.client_secret}
        )
        data = resp.json()
        self._token = data["access_token"]
        self._token_expiry = time.time() + data["expires_in"]
        return self._token
```

## Erros de Autenticação

| Status HTTP                 | Significado                                                          | Resolução                                                                                           |
| --------------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `400 Bad Request`           | O `client_id` ou `client_secret` está ausente na requisição do token | Certifique-se de que ambos os campos estão presentes e escritos corretamente no corpo da requisição |
| `401 Unauthorized`          | O token está ausente, inválido ou expirou                            | Autentique-se novamente chamando `/api/v1/auth/token` para obter um novo token                      |
| `429 Too Many Requests`     | Sua aplicação excedeu o limite de requisições                        | Aguarde e tente novamente após o período indicado no cabeçalho de resposta `Retry-After`            |
| `500 Internal Server Error` | Ocorreu um erro inesperado no servidor iGps                          | Tente novamente após um curto intervalo; entre em contato com o suporte iGps se o erro persistir    |

<Warning>
  Nunca compartilhe seu `client_secret` nem o envie para controle de versão. Use variáveis de ambiente para armazenar credenciais com segurança.
</Warning>