> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Ottieni sessione | API di autenticazione Didit > GET /session/ verifica un access token sulla sessione attiva in Didit: fallisce subito dopo revoca, timeout per inattività, blocco o refresh. > [!WARNING] > > L'autenticazione è nuova. Questi endpoint sono forniti dall'emittente della tua applicazione, ad esempio `https://.auth.didit.me`, e non accettano mai la tua chiave API Didit. Questo è il controllo di revoca istantaneo. Consente 30 richieste al minuto e 300 all'ora per indirizzo, quindi verifica i token offline a ogni richiesta e chiamalo prima delle operazioni sensibili. Vedi [Verifica la sessione](https://docs.didit.me/it/authentication/tokens-and-jwks.md#controlla-la-sessione). ## OpenAPI ````yaml it/openapi-authentication.json GET /session/ openapi: 3.0.3 info: title: Didit Authentication API version: 1.0.0 description: >- Gli endpoint lato server di Didit Authentication, il prodotto di accesso per gli utenti finali della tua applicazione. Authentication è una funzionalità **nuova** e raggiungerà l'ambiente di produzione nella release 2026-11-01. ## URL di base Ogni applicazione è un proprio emittente OpenID Connect e ogni endpoint indicato di seguito è servito alla radice di tale emittente: - `https://.auth.didit.me` per un'applicazione di produzione, o `https://.sandbox.auth.didit.me` per un'applicazione sandbox. - Il tuo dominio personalizzato, una volta attivo. Quest'ultimo sostituisce quindi l'host predefinito come emittente: i nuovi token lo indicano in `iss`, la discovery punta ad esso e la chiave pubblicabile cambia. I token di accesso emessi sotto l'host predefinito falliscono su `/session/`, `/step-up/` e `/monitoring-token/` fino al loro rinnovo. L'ambiente di produzione e la sandbox sono applicazioni separate, quindi sono emittenti separati con chiavi separate. La chiave pubblicabile è `pk_live_` (produzione) o `pk_test_` (sandbox) seguita dalla codifica base64url senza padding dell'emittente, senza barra finale: decodificala per trovare l'emittente. Si tratta di un identificatore pubblico, non di una credenziale. Gli stessi endpoint JSON sono serviti anche sotto `https://apx.didit.me/auth/v2/authentication/{application_id}/`. I token indicano sempre l'emittente sopra descritto, indipendentemente dall'indirizzo che li ha emessi. ## Credenziali Questi endpoint non richiedono mai la tua chiave API Didit o un token della console. - La discovery, il JWKS e `POST /token/` non richiedono credenziali. I client sono pubblici: non esiste alcun segreto client e il codice di autorizzazione è associato al relativo verificatore PKCE (`S256`). `client_id` è l'ID della tua applicazione. - `/session/`, `/step-up/` e `/monitoring-token/` richiedono il token di accesso della persona: `Authorization: Bearer `. Ogni chiamata riuscita conta come attività sulla sessione, quindi azzera e riavvia il timeout di inattività della sessione. ## Body della richiesta Ogni endpoint che accetta un body supporta formati JSON, form-encoded e multipart. Questo documento elenca JSON, oltre al formato form-encoded per `POST /token/` come inviato dai client OAuth. Un campo non accettato dall'endpoint restituisce `400 {"": "unknown_field"}`. ## Token - **Token di accesso**: un JWT ES256 con intestazione `typ: at+jwt`, valido per un massimo di 5 minuti e mai più a lungo della relativa sessione. Claim: `AccessTokenClaims`. - **ID token**: un JWT ES256 con intestazione `typ: JWT`. Claim: `IDTokenClaims`. Non viene mai accettato come token di accesso. - **Refresh token**: una stringa casuale che ruota a ogni utilizzo. L'invio di un refresh token già utilizzato revoca la sessione. Verifica un token con le chiavi restituite da `GET /.well-known/jwks.json`: l'algoritmo deve essere `ES256`, `typ` deve corrispondere al tipo di token, `iss` deve coincidere con l'emittente configurato e `aud` con l'ID della tua applicazione. La verifica offline rileva una sessione revocata solo dopo la scadenza del relativo token di accesso; `GET /session/` è il controllo istantaneo. ## Errori | Body | Quando | | --- | --- | | `{"error": ""}` | Errori restituiti da `POST /token/`, tutti con stato `400`, nella struttura del body definita dalla sezione 5.2 della [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749#section-5.2): `invalid_grant`, `invalid_client` e l'errore `mfa_required` di Didit. Errori del servizio: `temporarily_unavailable`, `monitoring_unavailable`, `monitoring_disabled`. | | `{"": [""]}` o `{"": ""}` | La convalida di un campo della richiesta non è riuscita. `non_field_errors` indica una regola applicata su più campi e `unknown_field` un campo non accettato dall'endpoint. | | `{"detail": ""}` | `401` (`invalid_token`), `403` (`origin_not_allowed`), `404` (applicazione o step-up sconosciuto) e `429` (limite di frequenza). Anche `400` per un body che non può essere analizzato (`JSON parse error - ...`), `405` per un metodo non gestito dall'endpoint e `415` per un `Content-Type` non supportato. | Uno stato `401` include inoltre l'intestazione `WWW-Authenticate: Bearer`, mentre un `429` include `Retry-After` in secondi. Due tipi di rifiuto non restituiscono JSON. Un indirizzo che non corrisponde a un emittente viene rifiutato prima di raggiungere questi endpoint, ad esempio con un `404` vuoto per un nome `*.auth.didit.me` non utilizzato. Un parametro `step_up_id` che non è un UUID restituisce una pagina `404`. ## Limiti di frequenza Una richiesta deve superare due livelli. **Limiti dell'endpoint**, conteggiati per indirizzo IP del client, per applicazione e per endpoint: - Discovery e JWKS: 1.200 richieste al minuto e 12.000 all'ora. - Tutti gli altri endpoint: 30 richieste al minuto e 300 all'ora. `GET` e `DELETE /session/` condividono un unico conteggio. Al superamento di un limite: `429 {"detail": "Too many requests from this IP address. Please wait before trying again. Expected available in 60 seconds."}`, oppure `3600 seconds` per il limite orario. **Protezione bot**, attiva su ogni `POST` e `DELETE`. I suoi bucket sono condivisi da tutte le richieste `POST` e `DELETE` dell'applicazione, inclusi i passaggi di accesso ospitati, e si ricaricano continuamente: - 60 richieste al minuto per indirizzo IP del client. - 30 richieste al minuto per dispositivo, per le richieste che identificano il dispositivo, come fanno gli SDK per browser e nativi. - 3.000 richieste al minuto per l'intera applicazione, considerando tutti gli indirizzi IP. I rinnovi dei token (`POST /token/` con `grant_type=refresh_token`) attingono invece a un bucket dedicato: 6.000 al minuto per l'intera applicazione. Al superamento di un bucket: `429 {"detail": "rate_limited Expected available in N seconds."}` (`1 second.` quando N è 1). Il bucket per IP si applica a diversi endpoint, quindi un singolo indirizzo che combina chiamate di token, step-up e disconnessione può esaurirlo prima di raggiungere il limite del singolo endpoint. Il bucket dell'applicazione conteggia ogni client dell'applicazione, inclusi i browser. Entrambi i livelli rispondono prima che l'endpoint venga eseguito, quindi una richiesta che ha ricevuto un codice `429` non è stata elaborata: effettua un nuovo tentativo dopo il tempo indicato in `Retry-After`, rinnovo incluso. ## Richieste del browser Una richiesta contenente un'intestazione `Origin` deve provenire da una delle origini dell'applicazione o dalle sue origini consentite, altrimenti riceve `403 origin_not_allowed`. Le richieste da server a server non inviano alcun `Origin`. ## Non trattati in questa sezione Questi percorsi servono le pagine ospitate, gli SDK nativi e per browser e gli agenti IA. Non fanno parte del contratto server e gli SDK server non li chiamano: - Passaggi di accesso: `POST /authorize/`, `POST /password/`, `/email/*`, `/phone/*`, `/password-reset/*`, `/passkeys/*`, `/mfa/*`, `/social/*` e `/protection/complete/`. - Pagine ospitate e callback: `/sign-in`, `/magic`, `/invite`, `/reset`, `/verify/`, `/sso/*`, `/wallet/callback/`, `/logo/` e i file di associazione delle app native sotto `/.well-known/`. - Accesso agenti: `/agents/*` e `/grants/`, compreso `GET /agents/session/`, il controllo in tempo reale del token di accesso di un agente IA. L'accesso degli agenti non fa parte di questa versione del contratto. - L'API di gestione della console per Authentication, che accetta sessioni della console. Gli eventi di Authentication non vengono ancora inviati come webhook, pertanto questo documento non definisce alcun webhook. servers: - url: https://{issuer} description: 'L''emittente (issuer) della tua applicazione: la sua origine di accesso.' variables: issuer: default: your-app.auth.didit.me description: >- L'host dell'emittente: `.auth.didit.me` (produzione), `.sandbox.auth.didit.me` (sandbox) o il tuo dominio personalizzato attivo. security: [] tags: - name: Issuer description: Chiavi di discovery e di firma, per verificare i token. - name: Tokens description: I grant di tipo authorization code e refresh. - name: Sessions description: Verifica e termina la sessione associata a un token di accesso. - name: Step-ups description: Verifica prima di un'azione sensibile. - name: Monitoring description: >- Credenziali del dispositivo per gli eventi di monitoraggio delle transazioni. paths: /session/: get: tags: - Sessions summary: Recupera la sessione description: >- Verifica il token di accesso rispetto alla sessione attiva e lo restituisce. Più rigoroso rispetto alla verifica autonoma del JWT: fallisce immediatamente se la sessione è stata revocata, è diventata inattiva o ha superato la sua durata massima, se la persona è stata bloccata o la sua email non è più verificata, se la sessione non rispetta più la tua politica MFA (ad esempio dopo che la persona ha aggiunto un'app di autenticazione o è diventata amministratore dell'organizzazione), o se il token è stato sostituito da un refresh. Usalo prima di un'azione sensibile, ad esempio un pagamento. Una verifica riuscita conta come attività, quindi riavvia il timeout di inattività della sessione. operationId: authentication_get_session responses: '200': description: La sessione è attiva. headers: Cache-Control: description: >- Sempre `no-store`: non memorizzare mai nella cache questa risposta. schema: type: string example: no-store Pragma: description: Sempre `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Session' examples: Session: summary: Una sessione con password value: sub: 1c9d8b88-1bff-43d1-ad7a-88b2bc0024e9 sid: c9abf6cc-2d64-4bf2-b31e-a4d09a070ab1 application_id: 7b0a6c2e-3f41-4c9a-8d55-1e2f3a4b5c6d vendor_data: user-42 amr: - password mfa_verified: false email: person@example.com email_verified: true phone: null verified_identity: null verified: null expires_at: '2026-11-16T10:41:14.347557Z' post_logout_redirect_uri: '' organizations: [] VerifiedMember: summary: Un membro verificato dell'organizzazione value: sub: 1c9d8b88-1bff-43d1-ad7a-88b2bc0024e9 sid: c9abf6cc-2d64-4bf2-b31e-a4d09a070ab1 application_id: 7b0a6c2e-3f41-4c9a-8d55-1e2f3a4b5c6d vendor_data: user-42 amr: - passkey mfa_verified: true email: person@example.com email_verified: true phone: '+34600000000' verified_identity: null verified: level: full_id over_18: true given_name: Alex country: ES expires_at: '2026-11-16T10:41:14.347557Z' post_logout_redirect_uri: https://app.example.com/ organizations: - organization_id: 3e9a1f0b-5c2d-4e7f-8a6b-9c0d1e2f3a4b organization__name: Northwind role: admin custom_role: null '401': $ref: '#/components/responses/InvalidToken' '403': $ref: '#/components/responses/OriginNotAllowed' '404': $ref: '#/components/responses/ApplicationNotFound' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/TemporarilyUnavailable' security: - AccessToken: [] components: schemas: Session: type: object description: La sessione live associata a un token di accesso. required: - sub - sid - application_id - vendor_data - amr - mfa_verified - email - email_verified - phone - verified_identity - verified - expires_at - post_logout_redirect_uri - organizations properties: sub: type: string format: uuid description: L'ID dell'identità. example: 1c9d8b88-1bff-43d1-ad7a-88b2bc0024e9 sid: type: string format: uuid description: L'ID della sessione. example: c9abf6cc-2d64-4bf2-b31e-a4d09a070ab1 application_id: type: string format: uuid example: 7b0a6c2e-3f41-4c9a-8d55-1e2f3a4b5c6d vendor_data: type: string description: >- Il riferimento della persona tra i vari prodotti Didit, come nei token. example: user-42 amr: $ref: '#/components/schemas/AuthenticationMethods' mfa_verified: type: boolean description: >- Indica se la sessione ha superato un secondo fattore. Sempre `true` per un accesso con passkey. example: false email: type: string format: email nullable: true example: person@example.com email_verified: type: boolean example: true phone: type: string nullable: true description: Numero di telefono E.164, o `null`. example: null verified_identity: $ref: '#/components/schemas/WalletVerification' verified: type: object nullable: true description: >- Livello di verifica e attestazioni selezionate, lo stesso oggetto che i token trasportano come `verified`, oppure `null` se assente. Leggi questo campo, non `email_verified`, per sapere se la persona ha verificato la propria identità. properties: level: type: string enum: - liveness - liveness_face_match - full_id description: >- Il livello più elevato superato. Dal più debole al più forte: `liveness`, `liveness_face_match`, `full_id`. example: full_id over_18: type: boolean example: true over_21: type: boolean example: true given_name: type: string example: Alex family_name: type: string example: Doe birthdate: type: string description: Data di nascita dal documento, `YYYY-MM-DD`. example: '1990-04-12' nationality: type: string description: Codice paese ISO 3166-1 alpha-2. example: ES country: type: string description: Codice ISO 3166-1 alpha-2 del paese del documento. example: ES document_verified: type: boolean example: true liveness: type: boolean example: true expires_at: type: string format: date-time description: >- Quando la sessione termina, al più tardi. Il timeout di inattività può terminarla prima. example: '2026-11-16T10:41:14.347557Z' post_logout_redirect_uri: type: string description: >- Indica dove l'applicazione reindirizza la persona dopo la disconnessione. Stringa vuota se non impostata. example: https://app.example.com/ organizations: type: array description: >- Ogni organizzazione cliente a cui appartiene la persona, quando le organizzazioni sono attivate. Vuoto altrimenti. items: $ref: '#/components/schemas/SessionOrganization' AuthenticationMethods: type: array description: >- La modalità di accesso della sessione, come valore singolo: ad esempio `password`, `code` (codice email), `magic` (link magico), `passkey`, `phone`, `sso`, `wallet` (Didit ID Wallet) o il nome di un metodo di accesso social. Vuoto per un token di agente. items: type: string example: - password WalletVerification: type: object description: >- Cosa ha condiviso il Didit ID Wallet all'accesso. `null` se la persona ha effettuato l'accesso in un altro modo. nullable: true required: - issuer - subject properties: issuer: type: string description: L'emittente del wallet. example: https://apx.didit.me/auth/idv subject: type: string description: L'ID della persona presso il wallet. example: 8b7f5c1e-2d3a-4b5c-9e8f-7a6b5c4d3e2f shared_session: type: object description: >- Una verifica che la persona ha scelto di condividere, che riscatti con la tua chiave API. properties: share_token: type: string session_id: type: string from_application_id: type: string claims: type: object description: >- Le informazioni verificate che la persona ha acconsentito a condividere, limitatamente a quanto richiesto dalla tua applicazione. additionalProperties: oneOf: - type: boolean - type: string example: over_18: true given_name: Alex SessionOrganization: type: object required: - organization_id - organization__name - role - custom_role properties: organization_id: type: string format: uuid example: 3e9a1f0b-5c2d-4e7f-8a6b-9c0d1e2f3a4b organization__name: type: string description: Il nome dell'organizzazione. example: Northwind role: type: string enum: - admin - member - billing example: admin custom_role: type: object nullable: true description: Il ruolo personalizzato assegnato al membro, oppure `null`. required: - key - permissions properties: key: type: string example: approver permissions: type: array items: type: string example: - payouts.approve Detail: type: object required: - detail properties: detail: type: string example: invalid_token OAuthError: title: OAuth error type: object description: Un errore OAuth (RFC 6749 sezione 5.2) o un errore di servizio. required: - error properties: error: type: string example: invalid_grant responses: InvalidToken: description: >- Il token di accesso è mancante, malformato, scaduto, firmato da un altro emittente o da un'altra chiave, è un token ID o un token agente, oppure è stato sostituito da un refresh; oppure la relativa sessione è stata revocata, è scaduta per inattività, ha superato la sua durata o non rispetta più la tua politica MFA, oppure la persona associata è stata bloccata o la sua email non è più verificata. Reindirizza la persona a eseguire nuovamente l'accesso. headers: WWW-Authenticate: description: '`Bearer`.' schema: type: string example: Bearer Cache-Control: description: 'Sempre `no-store`: non memorizzare mai nella cache questa risposta.' schema: type: string example: no-store Pragma: description: Sempre `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: InvalidToken: summary: Token di accesso rifiutato value: detail: invalid_token OriginNotAllowed: description: >- La richiesta conteneva un `Origin` che non appartiene all'applicazione né è tra le origini consentite. Le richieste server non inviano alcun `Origin`. headers: Cache-Control: description: 'Sempre `no-store`: non memorizzare mai nella cache questa risposta.' schema: type: string example: no-store Pragma: description: Sempre `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: OriginNotAllowed: summary: Origine non consentita value: detail: origin_not_allowed ApplicationNotFound: description: >- L'indirizzo appartiene a un'applicazione, ma l'Autenticazione non è attiva per essa; sull'indirizzo `apx.didit.me`, l'ID applicazione è sconosciuto. Un indirizzo che non appartiene ad alcuna applicazione viene rifiutato prima di raggiungere l'endpoint, e tale risposta non è in formato JSON. headers: Cache-Control: description: 'Sempre `no-store`: non memorizzare mai nella cache questa risposta.' schema: type: string example: no-store Pragma: description: Sempre `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: ApplicationNotFound: summary: Applicazione sconosciuta value: detail: No Configuration matches the given query. RateLimited: description: >- Troppe richieste da questo indirizzo IP per questo endpoint oppure, su un `POST` o un `DELETE`, un bucket di protezione dai bot è vuoto. Nessuna operazione eseguita: attendi `Retry-After` secondi, poi riprova. headers: Retry-After: description: Secondi da attendere prima di effettuare un nuovo tentativo. schema: type: integer example: 60 Cache-Control: description: 'Sempre `no-store`: non memorizzare mai nella cache questa risposta.' schema: type: string example: no-store Pragma: description: Sempre `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: RateLimited: summary: Limite dell'endpoint value: detail: >- Too many requests from this IP address. Please wait before trying again. Expected available in 60 seconds. BotProtection: summary: Limite di protezione dai bot (POST e DELETE) value: detail: rate_limited Expected available in 2 seconds. TemporarilyUnavailable: description: >- Un servizio da cui dipende la richiesta è temporaneamente non disponibile. Riprova con backoff. headers: Cache-Control: description: 'Sempre `no-store`: non memorizzare mai nella cache questa risposta.' schema: type: string example: no-store Pragma: description: Sempre `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/OAuthError' examples: TemporarilyUnavailable: summary: Riprova più tardi value: error: temporarily_unavailable securitySchemes: AccessToken: type: http scheme: bearer bearerFormat: JWT description: >- Il token di accesso della persona restituito da `POST /token/`: un JWT ES256 con intestazione `typ: at+jwt`, valido per un massimo di 5 minuti. Non la tua chiave API di Didit. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.