Chiavi API

Le chiavi API consentono di accedere ai vostri dati BeePass da applicazioni esterne, script o integrazioni di terze parti senza passare dall'interfaccia web. Ogni chiave dispone di permessi granulari per risorsa.

Funzionamento

[La vostra applicazione]
    │ Authorization: Bearer bp_live_a3f8...5e82
    ▼
https://beepass.io/api/v1/queens
    │ Validazione SHA-256 → ricerca DB → verifica permessi
    ▼
[Dati restituiti in JSON]

Create una chiave dall'interfaccia web (menu avatar → Chiavi API)
Copiate la chiave — verrà mostrata una sola volta
Utilizzatela nell'intestazione Authorization delle vostre richieste

Formato della chiave

bp_live_ + 64 caratteri esadecimali = 72 caratteri

Esempio: bp_live_a3f8e2b1c4d5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1

Sicurezza

La chiave in chiaro viene mostrata una sola volta al momento della creazione. BeePass conserva solo un hash SHA-256 — è impossibile recuperare una chiave smarrita. Dovrete crearne una nuova.

Utilizzo

Aggiungete la chiave nell'intestazione Authorization di ogni richiesta:

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()

Permessi

Ogni chiave definisce un livello di accesso per risorsa:

Risorsa	Descrizione
Queens	Regine F0 e F1 (ceppi, produzione)
Evaluations	Valutazioni delle prestazioni
BLUP	Valori genetici stimati (EBV)
Hive	Apiari e arnie
Account	Profilo e impostazioni dell'account

Livelli di permesso

Livello	Lettura (GET)	Scrittura (POST/PUT/DELETE)
Nessuno	-	-
Lettura	Si	-
Scrittura	Si	Si

suggerimento

Il livello Scrittura include automaticamente la lettura. Non è necessario definire entrambi.

Modelli predefiniti

Modello	Descrizione	Permessi
Sola lettura	Consultazione di tutti i dati	Tutte le risorse in lettura
Valutatore	Inserimento valutazioni sul campo	Valutazioni in scrittura, resto in lettura (eccetto Apiario)
Personalizzato	Configurazione manuale	Scegliete ogni permesso

Restrizioni

Scadenza (TTL)

Definite una durata di vita per la vostra chiave:

Opzione	Descrizione
7 giorni	Test e sviluppo
30 giorni	Integrazioni temporanee
90 giorni	Utilizzo standard
365 giorni	Integrazioni a lungo termine
Mai	Nessuna scadenza automatica

Una chiave scaduta viene automaticamente rifiutata. Resta visibile nell'elenco con lo stato "Scaduta".

Restrizione IP

Limitate l'utilizzo di una chiave a indirizzi IP specifici per rafforzare la sicurezza:

IP singolo: 203.0.113.5
Sottorete CIDR: 192.168.1.0/24

Se nessun IP è definito, la chiave può essere utilizzata da qualsiasi indirizzo.

info

La restrizione IP viene verificata ad ogni richiesta. L'IP del client viene estratto dalle intestazioni CF-Connecting-IP, X-Forwarded-For o X-Real-IP.

Gestione delle chiavi

Creare una chiave

Accedete alla pagina Chiavi API dal menu avatar nell'header, poi cliccate su Genera una chiave. La procedura guidata in 4 passaggi vi accompagna:

Nome — Scegliete un nome descrittivo e un modello di permessi
Permessi — Regolate i permessi per risorsa (modalità personalizzata)
Restrizioni — Definite la scadenza e gli IP autorizzati
Chiave generata — Copiate la vostra chiave immediatamente

Disattivare / Riattivare

Utilizzate lo switch nella colonna "Attiva" della tabella per disattivare temporaneamente una chiave senza eliminarla. Una chiave disattivata viene immediatamente rifiutata dall'API.

Revocare

Cliccate sull'icona cestino e confermate la revoca. La chiave passa allo stato "Revocata" e non può più essere riattivata.

Limiti

Limite	Valore
Numero massimo di chiavi per utente	20
Creazioni per ora	10
Lunghezza del nome	Da 1 a 100 caratteri

API di gestione

Le chiavi vengono gestite tramite l'API REST standard (autenticazione tramite sessione Supabase):

Metodo	Rotta	Descrizione
`GET`	`/api/api-keys`	Elencare le vostre chiavi (senza l'hash)
`POST`	`/api/api-keys`	Creare una nuova chiave
`PUT`	`/api/api-keys/{id}`	Modificare il nome o lo stato
`DELETE`	`/api/api-keys`	Revocare una chiave

Creare una chiave (POST)

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

Risposta (201):

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

Revocare una chiave (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" }'

Codici di errore

Codice	Situazione
`400`	Parametri non validi (nome, permessi, TTL, IP)
`400`	Massimo 20 chiavi raggiunto
`401`	Sessione non autenticata
`429`	Limite di creazione superato (10/h)

Permessi dettagliati

Ogni risorsa accetta tre livelli di accesso. Il livello write include automaticamente la lettura.

Risorsa	`none`	`read`	`write`
`queens`	Nessun accesso	Leggere le regine	Creare/modificare regine
`evaluations`	Nessun accesso	Leggere le valutazioni	Inviare valutazioni
`blup`	Nessun accesso	Leggere gli EBV	—
`hive`	Nessun accesso	Leggere gli apiari	Modificare gli apiari
`account`	Nessun accesso	Leggere il profilo	Modificare il profilo

info

La risorsa blup non prevede il livello write. I valori genetici sono calcolati dalla pipeline e non possono essere modificati tramite l'API.

Restrizione per IP

Potete limitare l'utilizzo di una chiave a un elenco di indirizzi IP autorizzati (allowlist). La notazione CIDR è supportata per autorizzare un'intera sottorete.

Esempi di valori accettati:

203.0.113.5 -- un singolo indirizzo IP
192.168.1.0/24 -- l'intera sottorete 192.168.1.x (256 indirizzi)
10.0.0.0/8 -- l'intera rete privata 10.x.x.x

Se l'elenco è vuoto, la chiave è utilizzabile da qualsiasi indirizzo. L'indirizzo del client viene estratto tramite le intestazioni CF-Connecting-IP, X-Forwarded-For o X-Real-IP.

Durata di validità

Ogni chiave dispone di una durata di vita (TTL) definita alla creazione:

Durata	Caso d'uso
7 giorni	Test e prototipazione
30 giorni	Integrazioni occasionali
90 giorni	Utilizzo corrente
1 anno	Integrazioni stabili
Illimitata	Nessuna scadenza automatica

Una chiave scaduta viene automaticamente rifiutata dall'API con il codice HTTP 401. Resta visibile nel vostro elenco di chiavi con lo stato Scaduta, ma non può più essere riattivata. Dovrete crearne una nuova.

attenzione

La chiave in chiaro viene mostrata una sola volta al momento della creazione. Copiatela immediatamente e conservatela in un gestore di segreti. BeePass conserva solo un hash SHA-256: è impossibile recuperare una chiave smarrita.

Vedi anche: Panoramica | Autenticazione | Regine | Valutazioni

Funzionamento​

Formato della chiave​

Utilizzo​

Permessi​

Livelli di permesso​

Modelli predefiniti​

Restrizioni​

Scadenza (TTL)​

Restrizione IP​

Gestione delle chiavi​

Creare una chiave​

Disattivare / Riattivare​

Revocare​

Limiti​

API di gestione​

Creare una chiave (POST)​

Revocare una chiave (DELETE)​

Codici di errore​

Permessi dettagliati​

Restrizione per IP​

Durata di validità​