Visao geral e autenticacao

Visão geral

Esta API tem dois tipos principais de autenticação:

• admin Usuário interno com acesso administrativo.
• api_user Usuário de integração, normalmente usado por sistemas clientes.

O header padrão é:

Authorization: Bearer <token>

O token de admin é obtido com login e senha. O token de API user é obtido por desafio criptográfico usando chave SSH.

Permissões de API user

As permissões atualmente disponíveis são:

• transaction:create
• transaction:read
• vault:create
• vault:read
• vault-address:create
• vault-address:read
• webhook:write
• webhook:read
• safe-token:write
• safe-token:read

Fluxo recomendado para integração com API user

1. Um admin cria o API user e registra a chave SSH pública.
2. O cliente chama POST /auth/challenge com o fingerprint da chave.
3. O cliente assina o challenge com a chave privada.
4. O cliente chama POST /auth/verify.
5. A API devolve um bearer token válido por 1 hora.

Autenticar um admin usando usuário e senha.

Endpoint: POST /admin/auth/login Autenticação

Não exige autenticação prévia.

Body

{
  "username": "admin",
  "password": "admin123"
}

Retorno

{
  "accessToken": "jwt",
  "tokenType": "Bearer",
  "expiresInSeconds": 28800,
  "admin": {
    "id": "uuid",
    "username": "admin"
  }
}

Gerar um desafio temporário para autenticação de API user com assinatura SSH.

Endpoint: POST /auth/challenge Autenticação

Não exige autenticação prévia.

Body

{
  "fingerprint": "SHA256:..."
}

Retorno

{
  "fingerprint": "SHA256:...",
  "challenge": "texto-aleatorio",
  "expiresAt": "2026-03-26T12:00:00.000Z"
}

Observações

• O fingerprint precisa pertencer a uma chave ativa cadastrada.
• O desafio expira e só pode ser usado uma vez.

Validar a assinatura do desafio e emitir o token do API user.

Endpoint: POST /auth/verify Autenticação

Não exige autenticação prévia.

Body

{
  "fingerprint": "SHA256:...",
  "challenge": "texto-aleatorio",
  "signature": "base64"
}

Retorno

{
  "accessToken": "jwt",
  "tokenType": "Bearer",
  "expiresInSeconds": 3600,
  "apiUser": {
    "id": "uuid",
    "name": "my-client",
    "permissions": [
      "vault:read",
      "transaction:create"
    ]
  }
}

Observações

• A assinatura deve ser em base64.
• O token de API user expira em 1 hora.

Descobrir quem é o usuário autenticado e quais permissões ele tem.

Endpoint: GET /auth/me Autenticação

Exige bearer token.

Retorno quando for admin

{
  "id": "uuid",
  "type": "admin",
  "username": "admin",
  "permissions": ["admin:*"]
}

Retorno quando for API user

{
  "id": "uuid",
  "type": "api_user",
  "fingerprint": "SHA256:...",
  "permissions": ["vault:read", "transaction:read"],
  "name": "my-client"
}