Autenticação
Métodos de autenticação
O Opero suporta dois métodos de autenticação:
1. Bearer Token (Sessão)
Usado por aplicações frontend e integrações que atuam em nome de um usuário.
Obter um token:
POST /api/auth/sign-in/email
Content-Type: application/json
{
"email": "usuario@hotel.com",
"password": "sua-senha-segura"
}Resposta:
{
"redirect": false,
"token": "Xk9bQ2...",
"user": {
"id": "id-do-usuario",
"email": "usuario@hotel.com",
"name": "Maria Silva",
"role": "admin"
}
}O token é um token de sessão opaco (não é um JWT). O login também define o cookie de sessão (__Secure-better-auth.session_token em HTTPS). Se o usuário tiver autenticação em dois fatores, a resposta pede a verificação do código antes de concluir o login.
Usar o token:
GET /api/tenants/:tenantId/reservations
Authorization: Bearer <token>Importante: A sessão expira após 7 dias. Depois disso, faça login novamente.
2. API Key
Usado por integrações servidor-a-servidor (channel managers, scripts, automações).
Criar uma API Key:
- Vá em Configurações → Chaves de API
- Clique em “New key”
- Defina um nome (label) e o escopo:
READ_ONLY(apenas leitura — GET) ouREAD_WRITE - Copie a chave (exibida apenas uma vez!)
A criação de chaves exige que o tenant tenha contratado o acesso à API na Loja. As chaves não expiram; uma chave revogada deixa de funcionar imediatamente.
Usar a API Key:
GET /api/tenants/:tenantId/reservations
X-API-Key: opk_abc123def456ghi789...A chave só é aceita no header X-API-Key. Uma chave READ_ONLY recebe 403 em métodos de escrita (POST, PUT, PATCH, DELETE).
Segurança: Nunca exponha API Keys em código frontend ou repositórios públicos. Use variáveis de ambiente.
Gerenciamento de sessões
Listar sessões ativas
GET /api/auth/sessions
Authorization: Bearer <token>Revogar uma sessão específica
DELETE /api/auth/sessions/:tokenPrefix
Authorization: Bearer <token>Revogar todas as sessões
POST /api/auth/revoke-all
Authorization: Bearer <token>Refresh token
POST /api/auth/refresh
Content-Type: application/json
{
"refreshToken": "<refresh-token>"
}Contexto de tenant
O tenant é definido pelo usuário autenticado (ou pela API Key). Superusuários da plataforma podem selecionar o tenant ativo:
PUT /api/auth/tenant-context
Authorization: Bearer <token>
Content-Type: application/json
{
"tenantId": "uuid-do-tenant"
}Isso vale apenas para superusuários. Usuários de tenant pertencem a um único tenant e não podem trocar de contexto.
Permissões (CASL)
A API respeita as permissões definidas pelo papel do usuário. Se um usuário com papel “Financeiro” tentar acessar um endpoint de gestão de usuários, receberá:
{
"code": "AUTHZ_INSUFFICIENT_PERMISSIONS",
"message": "Insufficient permissions",
"statusCode": 403,
"timestamp": "2026-05-25T14:30:00.000Z"
}Endpoints públicos (sem autenticação)
Os seguintes endpoints são acessíveis sem token — usados pelo portal de reservas público:
| Método | Endpoint | Descrição |
|---|---|---|
| GET | /api/public/property/:id/config | Configuração da propriedade |
| GET | /api/public/property/:id/rooms | Lista de quartos/tarifas |
| GET | /api/public/property/:id/availability | Disponibilidade |
| GET | /api/public/property/:id/gallery | Galeria de fotos |
| GET | /api/public/property/:id/payment-methods | Métodos de pagamento |
| POST | /api/public/reservations/hold | Criar hold de reserva |
| POST | /api/public/payments/create | Processar pagamento |
| POST | /api/public/reservations/confirm | Confirmar reserva |
| POST | /api/public/reservations/cancel | Cancelar reserva |
| GET | /api/public/payments/:id/status | Status do pagamento |
Exemplos de código
cURL
# Listar reservas
curl -X GET "https://api.opero.global/api/tenants/TENANT_ID/reservations?status=CONFIRMED" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json"JavaScript (fetch)
const response = await fetch(
`https://api.opero.global/api/tenants/${tenantId}/reservations`,
{
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
},
}
);
const data = await response.json();Python (requests)
import requests
response = requests.get(
f"https://api.opero.global/api/tenants/{tenant_id}/reservations",
headers={"Authorization": f"Bearer {token}"}
)
data = response.json()