Creare un'API

POST /v1/apis · permesso apis:write

Crea un'API nell'ambiente. key, identifier e name sono obbligatori; i campi opzionali omessi assumono i valori predefiniti. L'identificatore è univoco nell'ambiente (un'API eliminata mantiene l'identificatore riservato per 90 giorni). La risposta contiene un ETag con la versione attuale. Inviare un header Idempotency-Key per rendere i tentativi sicuri.

Richiesta

Body application/json. I campi sconosciuti vengono rifiutati.

Campo Tipo Obbligatorio Descrizione
key string sì Chiave di configurazione stabile, ^[a-z0-9_-]{1,64}$. Immutabile.
identifier string sì Audience del token: un URL https (senza query o frammento) oppure urn:<nid>:<nss>; archiviato in forma canonica. Immutabile. Lo spazio dei nomi urn:idp: è riservato.
name string sì 1-128 caratteri.
access_token_lifetime_s integer no 60-86400. Predefinito 3600 (600 con mcp_profile).
token_format string no jwt (predefinito) o opaque.
rbac_mode string no Modo in cui ruoli e permessi raggiungono il token: claims (predefinito) aggiunge permissions e org_permissions; off non aggiunge nessuno dei due (org_roles viene comunque aggiunto); enforce li aggiunge e limita inoltre gli scope concessi ai permessi effettivi dell'utente.
allow_offline_access boolean no Predefinito true.
require_resource_indicator boolean no Predefinito false (true con mcp_profile).
dpop_required boolean no Predefinito false.
mcp_profile boolean no Richiede un identifier https e require_resource_indicator: true.
first_party_access string no all (predefinito) o granted_only.
introspection_applications array no Applicazioni (app_…) che possono introspezionare i token di questa API, al massimo 50, senza duplicati. Solo applicazioni web e m2m dello stesso ambiente. Vuoto per impostazione predefinita.

Applicazioni di introspezione

L'endpoint di introspezione (POST <issuer>/oauth2/introspect, RFC 7662) risponde con active: true per un token di accesso solo a due chiamanti: l'applicazione a cui è stato emesso il token, oppure un'applicazione nell'elenco introspection_applications dell'API denominata nel aud del token. Tutti gli altri chiamanti ricevono active: false, quindi le API non possono leggere i token l'una dell'altra. Solo le applicazioni riservate (web, m2m) dello stesso ambiente possono essere elencate; l'elenco viene archiviato come un insieme e restituito in ordine ID. Un'applicazione sospesa rimane nell'elenco ma non può introspezionare. L'elenco dell'API di sistema non può essere scritto.

Risposta

201 Created con un header ETag e l'API:

{
  "id": "api_01h455vb4pex5vsknk084sn02q",
  "key": "orders",
  "identifier": "https://api.example.com/orders",
  "name": "Orders API",
  "is_system": false,
  "access_token_lifetime_s": 3600,
  "token_format": "jwt",
  "rbac_mode": "claims",
  "allow_offline_access": true,
  "require_resource_indicator": false,
  "dpop_required": false,
  "mcp_profile": false,
  "first_party_access": "all",
  "introspection_applications": ["app_01h455vb4pex5vsknk084sn02r"],
  "created_at": "2026-10-05T12:00:00Z",
  "updated_at": "2026-10-05T12:00:00Z"
}

Errori

HTTP code Quando
400 unknown_field Il body contiene un campo non elencato sopra (ad esempio id o is_system).
409 conflict Esiste già un'API con questa key o questo identifier.
415 unsupported_media_type Il content type non è application/json.
422 validation_failed Un campo è mancante o non valido (errors[].pointer, ad esempio /identifier).
422 validation_failed Un elemento introspection_applications non esiste in questo ambiente (unknown_application), non è riservato (not_confidential), è un duplicato (duplicate) o non è un ID app_… (invalid_value); il puntatore denomina l'indice nella richiesta.
403 quota_exceeded L'ambiente ha raggiunto il suo limite tecnico di API.
403 insufficient_permissions La credenziale non ha apis:write.

Esempio

curl -X POST https://api.eu.keenauth.com/v1/apis \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"key":"orders","identifier":"https://api.example.com/orders","name":"Orders API"}'