> ## 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.

# Registrazione programmatica tramite Auth API

> Crea organizzazioni Didit via Auth API, senza browser. Nativo per agenti, con KYC per sub-account. Pay-per-call, senza contratti.



Prompt per la registrazione programmatica
        Copia il prompt negli appunti



      
      

\<pre>

\``Programmatically create a pending Didit account — step 1 of the two-step onboarding (no browser, no console).

Endpoint:
POST https://apx.didit.me/auth/v2/programmatic/register/

Authentication:
None. This is a public endpoint. (Don't confuse the Auth API host `apx.didit.me/auth/v2` with the verification host `verification.didit.me/v3`.)

Request body:
\- email (string, required) — Any real, deliverable email (personal, work, alias). The verification code is mailed synchronously, so reserved test domains (`@example.com`, `@example.org`, `@*.test`, `@*.example`, `@*.invalid`) get rejected by mail delivery and the call returns `500` — substitute the placeholder with an inbox you can read.
\- password (string, required) — Must satisfy ALL of: minimum 8 characters, ≥1 uppercase letter (A-Z), ≥1 lowercase letter (a-z), ≥1 digit (0-9), ≥1 special character from !@#$%^&*()_+-=[]{}|;:,.<>?. Rules are validated one at a time and the first failure short-circuits.

curl example (replace `you@yourdomain.com` with a real inbox):
curl -X POST https://apx.didit.me/auth/v2/programmatic/register/ \
-H "Content-Type: application/json" \
-d '{
"email": "you@yourdomain.com",
"password": "MyStr0ng!Pass"
}'

Response (201 Created):
\- message (string) — "Registration successful. Check your email for the verification code."
\- email (string) — echoed back.

What happens server-side:
\- A pending account is created (NOT usable yet).
\- A 6-character alphanumeric code (e.g. "A3K9F2") is emailed to the supplied address.
\- The code is valid for 15 minutes. After expiry the registration must be redone.

Failure modes (all 400 unless noted):
\- Field-level: { "email": ["Enter a valid email address."] } or { "password": ["Ensure this field has at least 8 characters."] }.
\- Password-strength failures CURRENTLY return as a BARE ARRAY (no field key), one rule at a time: ["Password must contain at least one uppercase letter."] / lowercase / digit / special character. Known server-side inconsistency — treat as { "password": [...] } client-side.
\- Duplicate email: { "detail": "An account with this email already exists." }
\- 429 — { "detail": "Too many registration attempts. Please try again later.", "wait": <seconds> } when more than 5 registrations from the same IP within an hour.
\- 500 — returned (with an HTML body, not JSON) when mail delivery to the supplied address fails synchronously. Most commonly triggered by reserved test domains; use a real inbox.

Rate limits:
5 registrations per IP per hour.

Next step:
After receiving the email, call POST https://apx.didit.me/auth/v2/programmatic/verify-email/ with { "email", "code" } to get your access_token and api_key — see /auth-api/verify-email.

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.``

\</pre>



      
      

Incolla in



## OpenAPI

````yaml it/openapi-auth.json POST /programmatic/register/
openapi: 3.0.0
info:
  version: 1.0.0
  title: Didit Auth API
  description: >-
    API di registrazione e autenticazione programmatica per sviluppatori e
    agenti AI. Registrati in 2 chiamate API -- senza bisogno di browser. La
    piattaforma di verifica dell'identità più adatta agli agenti.


    ## Base URL


    Tutti gli endpoint di questa specifica sono ospitati su
    `https://apx.didit.me/auth/v2`. Si tratta di un host diverso rispetto a
    quello dell'API di verifica (`https://verification.didit.me/v3`).
    Distinguili chiaramente: questo host di autenticazione rilascia i tuoi
    **token di accesso JWT** e ti consente di elencare e gestire le tue
    **organizzazioni** e le tue **applicazioni**. L'host di verifica è il luogo
    in cui chiami sessioni, workflow, AML, ecc., autenticandoti con la
    **`api_key`** restituita da questa API.


    ## Come funziona il flusso di autenticazione


    1. `POST /programmatic/register/` — invia email + password.

    2. Ricevi un codice alfanumerico di 6 caratteri via email.

    3. `POST /programmatic/verify-email/` — invia il codice. Ricevi in risposta
    un `access_token` JWT, un `refresh_token`, un'organizzazione e
    un'applicazione predefinita con `client_id` + `api_key`.

    4. Salva la `api_key`. Usala come `x-api-key` per ogni chiamata a
    `https://verification.didit.me/v3/...`.

    5. Da qualsiasi macchina in futuro, `POST /programmatic/login/` scambia
    email + password con un nuovo JWT, quindi chiama `GET /organizations/me/` e
    gli endpoint dell'applicazione per recuperare o ruotare le credenziali.


    Il JWT serve solo per gli endpoint di **Gestione dell'account** in questa
    specifica; il traffico dell'API di verifica utilizza la `api_key` a lunga
    durata, non il JWT.


    ## Convenzioni


    - Tutti i corpi di richiesta e risposta sono in formato JSON (`Content-Type:
    application/json`).

    - **Usa un indirizzo email reale e recapitabile quando testi `POST
    /programmatic/register/`.** L'endpoint invia il codice di verifica in modo
    sincrono, quindi gli indirizzi su domini di test riservati (`@example.com`,
    `@example.org`, `@*.test`, `@*.example`, `@*.invalid`) vengono rifiutati
    dalla consegna della posta e la richiesta restituisce `500`. Sostituisci il
    segnaposto `you@yourdomain.com` negli esempi con una casella di posta che
    puoi effettivamente consultare.

    - Gli errori di validazione restituiscono HTTP `400` con una delle due
    strutture: `{"field": ["message", ...]}` per problemi a livello di campo,
    oppure `{"detail": "message"}` per errori legati a regole aziendali. Alcuni
    validatori (robustezza della password in fase di registrazione, scadenza del
    codice su verify-email) attualmente rispondono con un array semplice
    `["message"]` anziché con il formato indicizzato per campo: si tratta di
    un'incoerenza nota lato server, pertanto il codice client dovrebbe accettare
    entrambi i formati.

    - Gli errori di autenticazione vengono restituiti come `{"detail": "..."}`
    con HTTP `401` (token bearer non valido) o `403` (token bearer mancante /
    autorizzazioni insufficienti).

    - Le risposte relative al limite di frequenza includono un campo `wait` con
    il tempo di attesa in secondi.
servers:
  - url: https://apx.didit.me/auth/v2
    description: Server di autenticazione di produzione
security: []
tags:
  - name: Programmatic Auth
    description: >-
      Ciclo di vita dell'account basato su email e password: registrazione,
      verifica, accesso. Restituisce il JWT `access_token` utilizzato per gli
      endpoint di gestione dell'account, oltre a (in fase di verifica)
      `client_id` e `api_key` della tua prima applicazione.
  - name: Account Management
    description: >-
      Endpoint autenticati (bearer JWT) che elencano le organizzazioni e creano,
      recuperano o aggiornano le applicazioni. Usali per recuperare o ruotare la
      `api_key` con cui autentichi le chiamate API di verifica.
paths:
  /programmatic/register/:
    post:
      tags:
        - Programmatic Auth
      summary: Registra un account
      description: >-
        Passaggio 1 dell'onboarding programmatico. Crea un account in sospeso e
        invia un'email con un codice di 6 caratteri (TTL di 10 min). L'indirizzo
        viene verificato prima della creazione di qualsiasi account: se non è in
        grado di ricevere il codice restituisce 400 `email_undeliverable`.
        Limiti di frequenza: 5/IP/ora, più un budget orario condiviso per rete
        (/24 per IPv4, /64 per IPv6).
      operationId: programmatic_register
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
            examples:
              Gmail:
                summary: Registrati con un account Gmail personale
                value:
                  email: you@yourdomain.com
                  password: MyStr0ng!Pass
              Work:
                summary: Registrati con un'email aziendale
                value:
                  email: you@yourcompany.com
                  password: C0mplex#Pass1
      responses:
        '201':
          description: >-
            Registrazione completata con successo. Un codice di verifica
            alfanumerico di 6 caratteri (ad es. `A3K9F2`) è stato inviato via
            email all'indirizzo fornito ed è valido per 10 minuti. Chiama
            successivamente `POST /programmatic/verify-email/`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterResponse'
              examples:
                Success:
                  value:
                    message: >-
                      Registration successful. Check your email for the
                      verification code.
                    email: you@yourdomain.com
        '400':
          description: >-
            Errore di validazione. L'envelope previsto è `{"field": ["..."]}`
            per gli errori a livello di campo e `{"detail": "..."}` per gli
            errori delle regole aziendali (ad es. email duplicata). Le regole
            sulla robustezza della password rispondono attualmente con un array
            semplice `["..."]`, una regola alla volta -- incoerenza nota lato
            server; trattala come `{"password": ["..."]}` finché non verrà
            corretta. Quando l'indirizzo non può ricevere il codice (dominio
            monouso, riservato o di test, nessun server di posta, probabile
            errore di battitura o un indirizzo da cui in precedenza sono
            rimbalzate email), il corpo è `EmailUndeliverableError` con `code:
            "email_undeliverable"`; nessun account viene creato o modificato.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - $ref: '#/components/schemas/EmailUndeliverableError'
              examples:
                MissingFields:
                  summary: Corpo vuoto
                  value:
                    email:
                      - This field is required.
                    password:
                      - This field is required.
                InvalidEmail:
                  summary: Email non valida
                  value:
                    email:
                      - Enter a valid email address.
                PasswordTooShort:
                  summary: Password inferiore a 8 caratteri
                  value:
                    password:
                      - Ensure this field has at least 8 characters.
                PasswordMissingUppercase:
                  summary: Password senza una lettera maiuscola
                  value:
                    - Password must contain at least one uppercase letter.
                PasswordMissingLowercase:
                  summary: Password senza una lettera minuscola
                  value:
                    - Password must contain at least one lowercase letter.
                PasswordMissingDigit:
                  summary: Password senza una cifra
                  value:
                    - Password must contain at least one digit.
                PasswordMissingSpecial:
                  summary: Password senza un carattere speciale
                  value:
                    - >-
                      Password must contain at least one special character
                      (!@#$%^&*()_+-=[]{}|;:,.<>?).
                Duplicate:
                  summary: L'email è già associata a un account
                  value:
                    detail: An account with this email already exists.
                EmailUndeliverable:
                  summary: L'indirizzo non può ricevere email (dominio usa e getta)
                  value:
                    detail: >-
                      This email can't receive messages. Please use a different
                      email address.
                    code: email_undeliverable
                    reason: disposable_domain
                EmailLikelyTypo:
                  summary: Probabile refuso nel dominio
                  value:
                    detail: >-
                      This email can't receive messages. Please use a different
                      email address.
                    code: email_undeliverable
                    reason: possible_typo
                    suggestion: gmail.com
        '429':
          description: >-
            Limite di frequenza raggiunto. Più di 5 tentativi di registrazione
            dallo stesso indirizzo nell'ultima ora, oppure il budget orario per
            la rete del chiamante (/24 per IPv4, /64 per IPv6, condiviso tra
            registrazione e reinvii del codice) è esaurito. Entrambi includono
            `Retry-After: 3600`. Viene restituito anche, con un'intestazione
            `Retry-After: 5`, quando il servizio sta verificando
            contemporaneamente il numero massimo di password o codici possibile;
            riprova dopo il numero di secondi indicato.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
              examples:
                RateLimited:
                  value:
                    detail: Too many registration attempts. Please try again later.
                PasswordChecksBusy:
                  summary: Troppe verifiche della password in corso
                  value:
                    detail: >-
                      Too many sign-in attempts are being processed right now.
                      Please try again in a few seconds.
      security:
        - {}
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl -X POST https://apx.didit.me/auth/v2/programmatic/register/ \
              -H "Content-Type: application/json" \
              -d '{
                "email": "you@yourdomain.com",
                "password": "MyStr0ng!Pass"
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # This call needs no API key.
            client = Didit()

            result = client.account.register(
                email="you@yourdomain.com",
                password="MyStr0ng!Pass",
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: |-
            import Didit from "@didit-protocol/sdk-node";

            // This call needs no API key.
            const didit = new Didit();

            const result = await didit.account.register({
              email: "you@yourdomain.com",
              password: "MyStr0ng!Pass",
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// This call needs no API key.\nclient := didit.NewClient()\n\nresult, err := client.Account.Register(ctx, didit.RegisterRequest{\n\tEmail:    \"you@yourdomain.com\",\n\tPassword: \"MyStr0ng!Pass\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: |-
            import me.didit.Didit;
            import me.didit.types.RegisterRequest;

            // This call needs no API key.
            Didit client = new Didit();

            var result = client.account().register(RegisterRequest.builder()
                    .email("you@yourdomain.com")
                    .password("MyStr0ng!Pass")
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

            // This call needs no API key.
            $didit = new DiditClient();

            $result = $didit->account->register([
                'email' => 'you@yourdomain.com',
                'password' => 'MyStr0ng!Pass',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # This call needs no API key.
            didit = Didit::Client.new

            result = didit.account.register(
              email: "you@yourdomain.com",
              password: "MyStr0ng!Pass"
            )
            puts result.to_h
        - lang: csharp
          label: .NET
          source: |-
            using System;
            using System.Text.Json;
            using Didit;

            // This call needs no API key.
            using var client = new DiditClient();

            var result = await client.Account.RegisterAsync(new RegisterRequest
            {
                Email = "you@yourdomain.com",
                Password = "MyStr0ng!Pass",
            });
            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    RegisterRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
          description: >-
            Qualsiasi indirizzo email valido (personale, di lavoro, alias).
            Utilizzato come identificatore univoco dell'account.
          example: you@yourdomain.com
        password:
          type: string
          minLength: 8
          description: >-
            Minimo 8 caratteri. Deve contenere almeno una lettera maiuscola
            (`A-Z`), una lettera minuscola (`a-z`), una cifra (`0-9`) e un
            carattere speciale tra `!@#$%^&*()_+-=[]{}|;:,.<>?`. La validazione
            segnala una regola non soddisfatta alla volta.
          example: MyStr0ng!Pass
    RegisterResponse:
      type: object
      properties:
        message:
          type: string
          description: >-
            Conferma di facile lettura che il codice di verifica è stato
            inviato.
          example: Registration successful. Check your email for the verification code.
        email:
          type: string
          format: email
          description: L'indirizzo email a cui è stato inviato il codice di verifica.
          example: you@yourdomain.com
    ValidationError:
      description: >-
        Corpo dell'errore di validazione. La busta prevista è una mappa `{field:
        ["message", ...]}` per errori a livello di campo o una busta a chiave
        singola `{detail: "..."}` per errori sulle regole di business. Alcuni
        validatori (complessità della password alla registrazione, validità del
        codice in verify-email) attualmente rispondono con un array semplice
        `["message"]` -- incoerenza nota lato server. Lo schema seguente
        mantiene quel ramo con array semplice in modo che il codice client
        generato da questa specifica deserializzi le risposte correnti, ma il
        nuovo codice client dovrebbe trattarlo come la forma con chiave di campo
        pertinente (`{password: [...]}` o `{code: [...]}`) e il contratto del
        server convergerà su tale formato.
      oneOf:
        - type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            email:
              - Enter a valid email address.
        - type: object
          properties:
            detail:
              type: string
          example:
            detail: An account with this email already exists.
        - type: array
          items:
            type: string
          example:
            - Invalid or expired verification code.
    EmailUndeliverableError:
      type: object
      description: >-
        Restituito da `POST /programmatic/register/` quando l'indirizzo non può
        ricevere il codice di verifica. Il controllo viene eseguito prima che
        qualsiasi account venga creato o modificato, quindi non rimane alcuna
        traccia.
      required:
        - detail
        - code
        - reason
      properties:
        detail:
          type: string
          description: Messaggio di facile lettura.
          example: >-
            This email can't receive messages. Please use a different email
            address.
        code:
          type: string
          enum:
            - email_undeliverable
          description: Sempre `email_undeliverable`.
        reason:
          type: string
          enum:
            - invalid_address
            - reserved_domain
            - no_mail_records
            - disposable_domain
            - possible_typo
            - suppressed
          description: >-
            Il motivo per cui l'indirizzo è stato rifiutato: `invalid_address`
            (non è un indirizzo valido), `reserved_domain` (un dominio riservato
            o di test come `example.com`), `no_mail_records` (il dominio non ha
            un server di posta), `disposable_domain` (un provider di caselle
            postali usa e getta), `possible_typo` (un probabile errore di
            battitura di un provider comune; vedi `suggestion`), `suppressed`
            (l'indirizzo ha precedentemente generato un bounce o un reclamo).
        suggestion:
          type: string
          description: >-
            Il dominio probabilmente desiderato, presente solo quando il dominio
            sembra contenere un refuso (ad esempio `gmail.com` al posto di
            `gmial.com`). L'API non accetta conferme: registrati nuovamente con
            l'indirizzo corretto.
          example: gmail.com
    RateLimitError:
      type: object
      description: >-
        Risposta di limite di frequenza o blocco progressivo. `wait` è il tempo
        di attesa in secondi.
      properties:
        detail:
          type: string
          example: >-
            Too many login attempts from this IP address. Please wait before
            trying again.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.