Chaves API

As chaves API dao-lhe acesso aos seus dados BeePass a partir de aplicacoes externas, scripts ou integracoes de terceiros sem utilizar a interface web. Cada chave tem permissoes detalhadas por recurso.

Como funciona

[A sua aplicacao]
    | Authorization: Bearer bp_live_a3f8...5e82
    v
https://beepass.io/api/v1/queens
    | Validacao SHA-256 -> consulta BD -> verificacao de permissoes
    v
[Dados JSON de retorno]

1. Crie uma chave atraves da interface web (menu avatar -> Chaves API)
2. Copie a chave — e apresentada apenas uma vez
3. Utilize-a no header Authorization dos seus pedidos

Formato da chave

bp_live_ + 64 caracteres hexadecimais = 72 caracteres

Exemplo: bp_live_a3f8e2b1c4d5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1

Seguranca

A chave bruta e apresentada apenas uma vez no momento da criacao. O BeePass armazena apenas um hash SHA-256 — e impossivel recuperar uma chave perdida. Tera de criar uma nova.

Utilizacao

Adicione a chave ao header Authorization de cada pedido:

curl -H "Authorization: Bearer bp_live_a3f8..." \
     https://beepass.io/api/v1/queens

const response = await fetch('https://beepass.io/api/v1/queens', {
  headers: {
    'Authorization': 'Bearer bp_live_a3f8...',
    'Content-Type': 'application/json'
  }
});
const data = await response.json();

import requests

headers = {
    'Authorization': 'Bearer bp_live_a3f8...',
    'Content-Type': 'application/json'
}
response = requests.get('https://beepass.io/api/v1/queens', headers=headers)
data = response.json()

Permissoes

Cada chave define um nivel de acesso por recurso:

Recurso	Descricao
Queens	Rainhas F0 e F1 (material de criacao, producao)
Evaluations	Avaliacoes de desempenho
BLUP	Valores geneticos estimados (EBV)
Hive	Apiarios e colmeias
Account	Definicoes de perfil e conta

Niveis de permissao

Nivel	Leitura (GET)	Escrita (POST/PUT/DELETE)
Nenhum	-	-
Leitura	Sim	-
Escrita	Sim	Sim

dica

O nivel Escrita inclui automaticamente acesso de leitura. Nao precisa de definir ambos.

Modelos predefinidos

Modelo	Descricao	Permissoes
Apenas leitura	Consultar todos os dados	Todos os recursos em modo leitura
Avaliador	Entrada de avaliacoes de campo	Avaliacoes em modo escrita, restantes em leitura (exceto Hive)
Personalizado	Configuracao manual	Escolhe cada permissao

Restricoes

Data de expiracao (TTL)

Defina um tempo de vida para a sua chave:

Opcao	Descricao
7 dias	Testes e desenvolvimento
30 dias	Integracoes temporarias
90 dias	Utilizacao padrao
365 dias	Integracoes a longo prazo
Nunca	Sem expiracao automatica

Uma chave expirada e automaticamente recusada. Permanece visivel na lista com o estado "Expirada".

Restricao de IP

Restrinja a utilizacao da chave a enderecos IP especificos para maior seguranca:

• IP unico: 203.0.113.5
• Sub-rede CIDR: 192.168.1.0/24

Se nenhum IP for definido, a chave pode ser utilizada a partir de qualquer endereco.

informacao

A restricao de IP e verificada a cada pedido. O IP do cliente e extraido dos headers CF-Connecting-IP, X-Forwarded-For ou X-Real-IP.

Gestao de chaves

Criar uma chave

Aceda a pagina Chaves API atraves do menu avatar no cabecalho e clique em Gerar chave. O assistente de 4 passos guia-o:

1. Nome — Escolha um nome descritivo e um modelo de permissoes
2. Permissoes — Ajuste as permissoes por recurso (modo personalizado)
3. Restricoes — Defina a data de expiracao e os IPs autorizados
4. Chave gerada — Copie a sua chave imediatamente

Desativar / Reativar

Utilize o interruptor na coluna "Ativar" para desativar temporariamente uma chave sem a eliminar. Uma chave desativada e imediatamente recusada pela API.

Revogar

Clique no icone do caixote do lixo e confirme a revogacao. A chave passa para o estado "Revogada" e nao pode ser reativada.

Limites

Limite	Valor
Max chaves por utilizador	20
Criacao por hora	10
Comprimento do nome	1 a 100 caracteres

API de gestao

As chaves sao geridas atraves da API REST padrao (autenticacao por sessao Supabase):

Metodo	Rota	Descricao
GET	/api/api-keys	Listar as suas chaves (sem hash)
POST	/api/api-keys	Criar uma nova chave
PUT	/api/api-keys/{id}	Atualizar nome ou estado
DELETE	/api/api-keys	Revogar uma chave

Criar uma chave (POST)

curl -X POST https://beepass.io/api/api-keys \
  -H "Content-Type: application/json" \
  -b "sb-cookie=..." \
  -d '{
    "name": "A minha app movel",
    "permissions": {
      "queens": "read",
      "evaluations": "write",
      "blup": "read",
      "hive": "none",
      "account": "read"
    },
    "expires_in_days": 90,
    "ip_allowlist": ["203.0.113.0/24"]
  }'

Resposta (201):

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "bp_live_a3f8e2b1c4d5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1",
    "key_prefix": "bp_live_a3f8e2b1...f0a1"
  }
}

Revogar uma chave (DELETE)

curl -X DELETE https://beepass.io/api/api-keys \
  -H "Content-Type: application/json" \
  -b "sb-cookie=..." \
  -d '{ "id": "550e8400-e29b-41d4-a716-446655440000" }'

Codigos de erro

Codigo	Situacao
400	Parametros invalidos (nome, permissoes, TTL, IP)
400	Maximo de 20 chaves atingido
401	Sessao nao autenticada
429	Limite de criacao excedido (10/h)

---

Ver tambem: Visao geral | Autenticacao | Rainhas | Avaliacoes