Crea una connessione

POST /v1/connections · autorizzazione connections:write

Registra una nuova connessione nell'ambiente. Le connessioni che richiedono una configurazione del protocollo (social, enterprise) iniziano come inactive; attivale esplicitamente con :activate. Una connessione enterprise non può essere creata come active: una nuova connessione non può ancora avere un accesso di prova riuscito. Le impostazioni non devono contenere segreti. Un ambiente può contenere al massimo 100 connessioni e 20 connessioni social generiche (oidc_generic, oauth2_generic), e un'organizzazione al massimo 20 connessioni.

Richiesta

Corpo JSON (i campi sconosciuti vengono rifiutati con 400 unknown_field):

Campo Tipo Obbligatorio Descrizione
key stringa sì Chiave di configurazione stabile, ^[a-z0-9_-]{1,64}$, unica nell'ambiente, non modificabile.
type stringa sì database, passwordless, passkey, social o enterprise. Non modificabile.
strategy stringa sì Strategia per il tipo, ad esempio password, email_otp, google, saml. Non modificabile.
name stringa sì Da 1 a 128 caratteri, unica nell'ambiente.
display_name stringa no Da 1 a 128 caratteri mostrati nelle schermate di accesso.
status stringa no active o inactive. Il valore predefinito è active per database, passwordless, passkey e inactive per social, enterprise.
org_id stringa no Organizzazione proprietaria (org_…), solo per enterprise. Se omesso: una connessione di ambiente. Non modificabile.
allowed_email_domains array di stringhe no Domini email instradati a questa connessione tramite home realm discovery: etichetta A IDNA, minuscola (ad esempio xn--bcher-kva.example), unica, al massimo 100; non vuota solo per enterprise. In una connessione di organizzazione ogni dominio deve essere un dominio verificato dell'organizzazione, e una connessione di organizzazione active ne richiede almeno uno.
allow_external_domains booleano no Consente anche l'accesso agli utenti il cui dominio email non è nell'elenco. Solo enterprise; predefinito false.
jit_mode stringa no Provisioning just-in-time: create crea l'utente al primo accesso, create_and_update aggiorna anche il profilo dal provider di identità, off richiede un account esistente. Solo enterprise. Il valore predefinito è create_and_update per una connessione di ambiente e off per una connessione di organizzazione.
email_trust booleano no Considera attendibile l'indirizzo email dichiarato dal provider di identità per il collegamento automatico degli account e il provisioning just-in-time. Solo enterprise; predefinito false. In una connessione di organizzazione true richiede un allowed_email_domains non vuoto in cui ogni dominio è un dominio verificato dell'organizzazione.
default_role_ids array di stringhe no Ruoli dell'ambiente (rol_…, unici, al massimo 10) assegnati all'appartenenza creata da un accesso just-in-time, oltre al ruolo predefinito dell'ambiente e alle mappature di ruolo di gruppo della connessione. Solo per una connessione enterprise di organizzazione. Ogni ruolo deve essere un ruolo non privilegiato di questo ambiente; un ruolo di un altro ambiente, un ruolo di organizzazione, un ruolo privilegiato o un ruolo mancante viene rifiutato. Un ruolo eliminato o reso privilegiato in seguito viene ignorato durante l'accesso.
trust_idp_mfa booleano no Accetta l'autenticazione a più fattori dichiarata dal provider di identità (contesto di autenticazione SAML, amr/acr di OIDC) come prova MFA della sessione. Solo enterprise; predefinito false.
settings oggetto no Impostazioni senza segreti, fino a 32 KiB. Chiavi o valori che sembrano segreti vengono rifiutati.
Idempotency-Key intestazione no Chiave facoltativa (da 16 a 64 caratteri) che rende sicura la ripetizione di una richiesta.

Risposta

201 Created con la connessione e un'intestazione ETag che contiene la sua versione.

{
  "id": "conn_0k3v8m1q2x9dz4h7s5t6w0y1ab",
  "key": "google",
  "type": "social",
  "strategy": "google",
  "name": "Google",
  "display_name": "Sign in with Google",
  "status": "inactive",
  "org_id": null,
  "allowed_email_domains": [],
  "allow_external_domains": false,
  "jit_mode": null,
  "email_trust": null,
  "default_role_ids": [],
  "trust_idp_mfa": null,
  "allow_idp_initiated": null,
  "idp_initiated_default_application_id": null,
  "idp_initiated_allowed_application_ids": [],
  "settings": {},
  "created_at": "2026-10-05T09:30:00.123456Z",
  "updated_at": "2026-10-05T09:30:00.123456Z"
}

Impostazioni passkey

Per type: "passkey" l'oggetto settings accetta solo le chiavi sotto indicate. Qualsiasi altra chiave, un tipo errato o un valore fuori intervallo viene rifiutato con 422 validation_failed e un errors[].pointer come /settings/max_credentials_per_user. Un valore null indica il valore predefinito. Gli errori di forma vengono segnalati prima di quelli di piano.

Chiave Tipo Note
rp_id stringa Assente, null o vuota: ogni host di accesso è il proprio rpId. Altrimenti il nome host di un dominio personalizzato active dell'ambiente (minuscolo, etichetta A IDNA); qualsiasi altro valore dà 422 validation_failed (/settings/rp_id). Una volta che l'ambiente ha passkey, modificala con Modifica del passkey rpId.
rp_name stringa Fino a 128 caratteri.
passkey_first_factor_enabled, security_key_second_factor_enabled booleano Predefinito true.
user_verification stringa preferred (predefinito) o required.
max_credentials_per_user intero Da 1 a 20, predefinito 20; le frazioni vengono rifiutate.
require_device_bound_passkeys booleano Vincolato al piano: true richiede Startup.
attestation_required booleano Vincolato al piano: true richiede Enterprise.
aaguid_allowlist, aaguid_blocklist array di stringhe UUID Al massimo 500 voci uniche ciascuno (gli errori puntano a /settings/<chiave>/<indice>). Vincolato al piano: un elenco non vuoto richiede Enterprise.
related_origins array di stringhe Origini https://host[:port]. Vincolato al piano: un elenco non vuoto richiede Enterprise.
passkey_enrollment_prompt stringa off o after_login (predefinito).

Scrivere un valore non predefinito di una chiave vincolata al piano fallisce con 403 plan_feature_unavailable e i membri feature e required_plan. Finché i diritti del piano non sono disponibili, queste chiavi non possono essere impostate in nessun ambiente; scrivere un valore predefinito (false, [], null) o rimuovere la chiave è sempre consentito. Quando la funzione è disponibile, ogni voce di related_origins deve essere un dominio personalizzato verificato e attivo dell'ambiente, altrimenti la richiesta fallisce con 422 related_origin_not_verified.

Errori

HTTP code Quando
400 unknown_field Il corpo contiene un campo sconosciuto.
403 quota_exceeded È stato raggiunto un limite di connessioni dell'ambiente o dell'organizzazione (org_id).
409 conflict Esiste già una connessione con la stessa key o name.
409 connection_test_required La richiesta crea una connessione enterprise con status: active; non viene scritto nulla. Creala inactive, testa il suo accesso, poi attivala con :activate.
415 unsupported_media_type Il tipo di contenuto non è application/json.
422 validation_failed Un campo manca o non è valido; errors[].pointer lo indica (ad esempio /settings/client_secret per impostazioni simili a segreti).
422 related_origin_not_verified Un'origine correlata non è un dominio personalizzato verificato dell'ambiente.
403 plan_feature_unavailable Il piano non include un'impostazione che hai scelto (membri feature, required_plan), ad esempio attestation_required.
401 unauthenticated La credenziale manca, non è valida o è stata revocata.
403 insufficient_permissions La credenziale non ha l'autorizzazione richiesta.
429 rate_limited È stato superato il limite di richieste; riprova dopo il periodo indicato in Retry-After.
503 service_unavailable Una dipendenza è temporaneamente non disponibile; riprova dopo il periodo indicato in Retry-After.

Esempio

curl -X POST https://api.eu.keenauth.com/v1/connections \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"google","type":"social","strategy":"google","name":"Google"}'