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