Referência da API

Base: https://api.rempar.org/v1. JSON em todo o lado. As respostas bem-sucedidas vêm envolvidas em {"data": ...}, os erros em {"error": {"code": "...", "message": "..."}}. Autenticação por token Bearer próprio de cada dispositivo.

A API é de conhecimento zero: nunca recebe palavras-passe nem conteúdo em texto simples. Os clientes de terceiros são bem-vindos, desde que respeitem o protocolo v1.

Estado

GET /v1/health
→ { "data": { "status": "ok", "release": "1.1.0" } }

Autenticação

Método Rota Corpo Resposta
POST /auth/prelogin {email} {kdf, kdf_salt}. Sal fictício determinístico se o e-mail for desconhecido.
POST /auth/register {email, auth_key, kdf, kdf_salt, device} 201 {status: "verification_sent"}. É enviado por e-mail um código de seis dígitos.
POST /auth/verify-email {email, code} {}
POST /auth/login {email, auth_key, device, totp?, code?} {tokens, device_id, vault_key_sealed?}. Erro totp_required (403) se a 2FA estiver ativa e o código faltar. Depois email_code_required (403): é enviado por e-mail um código de seis dígitos, a devolver em code para obter os tokens (10 min, 5 tentativas).
POST /auth/refresh {refresh_token} {access_token, refresh_token, ...}. Rotação; uma reutilização revoga o dispositivo.
POST /auth/logout Revoga o dispositivo atual.
POST /auth/recover {email, recovery_auth, totp?} Prova do kit de recuperação: devolve {vault_key_recovery, recovery_token} (15 min). totp_required se a 2FA estiver ativa.
POST /auth/recover/complete {email, recovery_token, auth_key, kdf, kdf_salt, vault_key_sealed, device} Nova palavra-passe mestra: substitui a chave de autenticação e a chave do cofre novamente selada, revoga todos os outros dispositivos e inicia sessão neste ({tokens, device_id, vault_key_sealed}).

device: {name, platform, client_id}, em que client_id é um UUID escolhido pelo cliente, estável para este dispositivo.

kdf: {"algo": "argon2id", "m": 65536, "t": 3, "p": 4}. Os clientes recusam parâmetros mais fracos do que m=19456, t=2, p=1.

Conta

Método Rota Descrição
GET /account E-mail, estado da 2FA, revisão do cofre, subscrição {plan, active, until}.
GET /account/subscription Apenas a subscrição.
POST /account/password Substitui auth_key após uma alteração da palavra-passe mestra. O cliente publica primeiro a chave do cofre novamente selada.
GET /account/devices Dispositivos ativos.
DELETE /account/devices/{id} Revoga um dispositivo.
POST /account/totp/setup Gera um segredo e devolve {secret, otpauth_url}.
POST /account/totp/enable {code}: ativa a 2FA.
POST /account/totp/disable {code}: desativa a 2FA.

Cofre

Método Rota Descrição
PUT /vault/key {vault_key_sealed, vault_key_recovery?}: apenas blobs selados, substituídos de forma atómica. Sempre permitido (restauro).
GET /vault/items?since=<revision>&limit=500 {items: [{id, revision, deleted, blob, updated_at}], revision}. Requer uma subscrição ativa.
POST /vault/items {base_revision, items: [{id, blob|null}]} → {revision, conflicts: []}. blob: null elimina (lápide). Se base_revision estiver desatualizada, o servidor devolve newer_items em vez de escrever. Máximo de 500 itens por envio. Requer uma subscrição ativa.

Subscrição

A subscrição Cloud começa com uma avaliação gratuita de 7 dias (trial), iniciada através do Stripe, da App Store ou do Google Play (ver GET /v1/account/subscription). Sem subscrição ativa, as rotas de sincronização respondem 402 subscription_required; a chave do cofre selada continua legível para permitir um restauro. O cliente mostra «Pendente» e continua em modo local.

Códigos de erro

Código HTTP Significado
invalid_credentials 401 E-mail, chave ou código incorreto.
unauthenticated 401 Token em falta, expirado ou dispositivo revogado.
email_unverified 403 Código de e-mail não introduzido.
totp_required 403 Fornecer totp.
subscription_required 402 Subscrição Cloud expirada.
email_taken 409 Já existe uma conta verificada com este e-mail.
stale_revision 409 Obter primeiro os newer_items devolvidos.
token_reused 401 Reutilização detetada, dispositivo revogado.

Limites de pedidos

Pré-início de sessão 30/min, registo e verificação 10/min, início de sessão 15/min, renovação 30/min, rotas autenticadas 240/min por dispositivo.

Exemplo

curl -s https://api.rempar.org/v1/auth/prelogin \
  -H 'Content-Type: application/json' \
  -d '{"email":"vous@example.org"}'

Tem uma pergunta sem resposta aqui? support@rempar.org