Skip to Content
API ReferenceAutenticação

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:

  1. Vá em Configurações → Chaves de API
  2. Clique em “New key”
  3. Defina um nome (label) e o escopo: READ_ONLY (apenas leitura — GET) ou READ_WRITE
  4. 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étodoEndpointDescrição
GET/api/public/property/:id/configConfiguração da propriedade
GET/api/public/property/:id/roomsLista de quartos/tarifas
GET/api/public/property/:id/availabilityDisponibilidade
GET/api/public/property/:id/galleryGaleria de fotos
GET/api/public/property/:id/payment-methodsMétodos de pagamento
POST/api/public/reservations/holdCriar hold de reserva
POST/api/public/payments/createProcessar pagamento
POST/api/public/reservations/confirmConfirmar reserva
POST/api/public/reservations/cancelCancelar reserva
GET/api/public/payments/:id/statusStatus 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()
Last updated on