Riferimento API

Autenticazione

Come creare e usare chiavi API per autenticarti con l'API FloopFloop.

Ultimo aggiornamento:

Autenticazione con chiave API

Tutte le richieste API devono includere la tua chiave API nell'headerAuthorization usando lo schema Bearer token:

Authorization: Bearer flp_your_api_key_here

Creazione delle chiavi API

Vai su Account → API Keys nella tua dashboard FloopFloop per creare e gestire le chiavi API.

  • Ogni account può avere fino a 5 chiavi API attive
  • Le chiavi vengono mostrate una sola volta alla creazione — conservale in modo sicuro
  • Le chiavi possono essere revocate in qualsiasi momento dalla dashboard
  • Tutte le chiavi iniziano con il prefisso flp_

Sicurezza delle chiavi

  • Non condividere mai le tue chiavi API né inserirle nel controllo versione
  • Usa variabili d'ambiente per memorizzare le chiavi nelle tue applicazioni
  • Ruota le chiavi regolarmente e revoca quelle non utilizzate
  • Ogni chiave ha il proprio bucket di limite di velocità

Limiti di velocità

Gli endpoint API hanno i seguenti limiti di velocità per chiave API:

OperationLimitWindow
Operazioni di lettura (GET)120 requests1 minute
Operazioni di scrittura (POST/PATCH/DELETE)30 requests1 minute
Deploy/Rollback5 requests1 hour
Creazione progetto/Clone10 requests1 hour

Le informazioni sul limite di velocità sono incluse negli header della risposta: X-RateLimit-Remaining e X-RateLimit-Reset.

Verifica dell'autenticazione

GET /api/v1/user/me

Usa questo endpoint per confermare che la tua chiave API sia valida. Restituisce il profilo dell'utente autenticato ed è la chiamata standard “testa la tua autenticazione” usata da tutti gli SDK ufficiali e da floop whoami nella CLI.

curl https://floopfloop.com/api/v1/user/me \
  -H "Authorization: Bearer flp_your_api_key_here"

Risposta (200):

{
  "data": {
    "id": "user_abc123",
    "email": "you@example.com",
    "name": "Your Name",
    "role": "user",
    "source": "api_key"
  }
}
  • role — "user" per gli account normali, "admin" per il personale della piattaforma.
  • source — come è stata autenticata la richiesta. "api_key" per le credenziali programmatiche, "cli_token" per il flusso CLI autorizzato dal dispositivo.

Un 401 UNAUTHORIZEDqui significa che la chiave è assente, revocata o malformata. Un 403 FORBIDDENsignifica che l'account esiste ma non ha il piano Business che condiziona l'accesso all'API (vedi Requisiti nella Panoramica API).

Gestione programmatica delle chiavi API

La maggior parte degli utenti crea le chiavi dalla dashboard, ma la stessa funzionalità è disponibile tramite API per scenari di orchestrazione — ruotare una chiave da un job CI, elencare le chiavi per verificare l'utilizzo, o revocare una chiave compromessa senza accedere all'interfaccia. Questo rispecchia ciò che floop keys list/create/remove fa nella CLI.

Elenco delle chiavi API

GET /api/v1/api-keys

Restituisce i metadati di ogni chiave attiva (non revocata) sull'account. Il materiale della chiave in chiaro non viene mai restituito — solo il keyPrefix (i primi 8 caratteri esadecimali della chiave, con prefisso flp_).

{
  "data": {
    "keys": [
      {
        "id": "key_abc",
        "name": "ci-deploy",
        "keyPrefix": "flp_a1b2c3d4",
        "scopes": null,
        "lastUsedAt": "2026-04-24T18:30:00Z",
        "createdAt": "2026-04-01T12:00:00Z"
      }
    ]
  }
}

Creazione di una chiave API

POST /api/v1/api-keys
{
  "name": "ci-deploy"    // required, 1-100 chars
}

Risposta (201):

{
  "data": {
    "id": "key_xyz",
    "rawKey": "flp_a1b2c3d4…full-40-hex…",
    "keyPrefix": "flp_a1b2c3d4"
  }
}

La rawKey viene mostrata una sola volta— le letture successive restituiscono solo il keyPrefix. Salvala immediatamente. Ogni account è limitato a 5 chiavi attive; se raggiungi il limite la richiesta restituisce409 LIMIT_EXCEEDED— revoca prima una chiave non utilizzata.

La creazione di una chiave richiede il piano Business. Una richiesta da un account non Business restituisce 403 FORBIDDEN con il messaggio “Creating API keys requires the Business plan”. Gli amministratori della piattaforma bypassano questo controllo.

Revoca di una chiave API

DELETE /api/v1/api-keys/{keyId}

Passa l'id della chiave (ad es.key_xyz) come parametro del percorso. La chiave viene invalidata immediatamente — le richieste già in volo su un worker possono completarsi, ma nessuna nuova richiesta si autenticherà.

Risposta (200):

{ "data": { "success": true } }
  • L'auto-revoca è bloccata. Chiamare DELETE con la stessa chiave che effettua la richiesta restituisce400 VALIDATION_ERROR— questo impedisce alla CLI di disconnettersi a metà operazione. Usa una chiave diversa o revoca dalla dashboard.
  • Le chiavi sconosciute o già revocate restituiscono404 NOT_FOUND.

Gli SDK ufficiali accettano sia un id che un nome di chiave nei loro helper apiKeys.remove(), risolvendo nome → id lato client tramite una chiamata di lista. L'API stessa accetta solo l'id.

Una chiave revocata non può essere ripristinata; crea una nuova per sostituirla. La revoca viene registrata nel log di audit mostrato su Account → API Keys.

PrecedentePanoramica APISuccessivoProgetti