Autenticação

Toda requisição à API da Avoei precisa de um token de API. O token identifica a sua agência e autoriza a leitura dos dados dela. Sem ele, a API responde 401.

Como enviar o token

Envie o token no cabeçalho Authorization, com a palavra Bearer antes dele:

Authorization: Bearer SEU_TOKEN

Um exemplo completo:

cURL

curl https://minhaagencia.avoei.com.br/api/v1/travels \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Accept: application/json"

JavaScript

const response = await fetch('https://minhaagencia.avoei.com.br/api/v1/travels', {
  headers: {
    Authorization: `Bearer ${process.env.AVOEI_TOKEN}`,
    Accept: 'application/json',
  },
});

PHP

$curl = curl_init('https://minhaagencia.avoei.com.br/api/v1/travels');

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AVOEI_TOKEN'),
        'Accept: application/json',
    ],
]);

$response = curl_exec($curl);

Python

import os
import requests

response = requests.get(
    "https://minhaagencia.avoei.com.br/api/v1/travels",
    headers={
        "Authorization": f"Bearer {os.environ['AVOEI_TOKEN']}",
        "Accept": "application/json",
    },
)

Nos exemplos, SEU_TOKEN é o valor que você copia ao criar o token e AVOEI_TOKEN é uma variável de ambiente que guarda esse valor. Nunca escreva um token real dentro do código.

observação

O cabeçalho Accept: application/json não é obrigatório, mas é uma boa prática: ele deixa claro que o seu sistema espera JSON.

O que o token permite

• Um token vale para uma agência. Ele só funciona no endereço da agência onde foi criado. Um token de outra agência, ou de um endereço diferente, resulta em 401.
• Todos os tokens têm o mesmo acesso. Hoje não existem níveis de permissão por token: qualquer token válido pode consultar todos os endpoints da referência da API, que são somente de leitura.
• O token não tem data de validade. Ele vale até ser revogado. Por isso, revogue tokens que não são mais usados. Veja Tokens de API.

Formas que não funcionam

O token só é aceito no cabeçalho Authorization. Não envie o token na URL (por exemplo, ?token=...) nem no corpo da requisição.

Erro 401: o que fazer

Se o token estiver ausente, incorreto ou revogado, a resposta é:

{
  "message": "Unauthenticated."
}

Confira estes pontos, na ordem:

1. O cabeçalho é exatamente Authorization: Bearer SEU_TOKEN, com a palavra Bearer e um espaço antes do token?
2. O token foi copiado por inteiro, sem espaços ou quebras de linha no início ou no fim?
3. O token ainda existe em Configurações > API Tokens no painel? Se foi excluído, ele não funciona mais.
4. O endereço da requisição é o da mesma agência que gerou o token?

Se nada resolver, gere um novo token. Veja outros erros em Erros.

Cuide bem do seu token

Quem tem o token consegue consultar os dados da agência. Use-o apenas em sistemas que rodam em um servidor seu (o back-end) e nunca o coloque em código que é entregue ao navegador ou ao aplicativo do cliente:

Visitante  →  site da agência  →  servidor do site  →  API da Avoei
                                  (guarda o token)

Veja mais em Boas práticas.