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

# Registre programàtic a l'Auth API

> Crea organitzacions de Didit amb l'Auth API, sense navegador i pensada per a agents. Pagament per crida i sense contractes.



Prompt de registre programàtic
        Copia el prompt al porta-retalls



      
      

\<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>



      
      

Enganxa a



## OpenAPI

````yaml ca/openapi-auth.json POST /programmatic/register/
openapi: 3.0.0
info:
  version: 1.0.0
  title: Didit Auth API
  description: >-
    API de registre i autenticació programàtica per a desenvolupadors i agents
    d'IA. Registra't en 2 crides d'API -- sense necessitat de navegador. La
    plataforma de verificació d'identitat més adaptada a agents.


    ## Base URL


    Tots els endpoints d'aquesta especificació estan allotjats a
    `https://apx.didit.me/auth/v2`. És un amfitrió diferent del de l'API de
    verificació (`https://verification.didit.me/v3`). Tingues-ho en compte:
    aquest amfitrió d'autenticació emet els teus **tokens d'accés JWT** i et
    permet llistar i gestionar les teves **organitzacions** i **aplicacions**.
    L'amfitrió de verificació és on crides sessions, fluxos de treball, AML,
    etc., i t'hi autentiques amb la **`api_key`** que retorna aquesta API.


    ## Com funciona el flux d'autenticació


    1. `POST /programmatic/register/` — envia correu electrònic + contrasenya.

    2. Rep un codi alfanumèric de 6 caràcters per correu electrònic.

    3. `POST /programmatic/verify-email/` — envia el codi. Reps com a resposta
    un `access_token` JWT, un `refresh_token`, una organització i una aplicació
    predeterminada amb `client_id` + `api_key`.

    4. Guarda la `api_key`. Fes-la servir com a `x-api-key` per a cada crida a
    `https://verification.didit.me/v3/...`.

    5. Des de qualsevol màquina en el futur, `POST /programmatic/login/`
    bescanvia el teu correu electrònic + contrasenya per un JWT nou; després
    crida `GET /organizations/me/` i els endpoints d'aplicació per recuperar o
    rotar credencials.


    El JWT només és necessari per als endpoints de **Gestió de comptes**
    d'aquesta especificació; el trànsit de l'API de verificació utilitza la
    `api_key` de llarga durada, no el JWT.


    ## Convencions


    - Tots els cossos de sol·licitud i resposta són JSON (`Content-Type:
    application/json`).

    - **Utilitza una adreça de correu electrònic real i que pugui rebre
    missatges quan provis `POST /programmatic/register/`.** L'endpoint envia el
    codi de verificació de manera síncrona, de manera que les adreces en dominis
    de prova reservats (`@example.com`, `@example.org`, `@*.test`, `@*.example`,
    `@*.invalid`) són rebutjades pel lliurament de correu i la sol·licitud
    retorna un `500`. Substitueix el marcador de posició `you@yourdomain.com`
    dels exemples per una bústia d'entrada que puguis llegir realment.

    - Els errors de validació retornen HTTP `400` amb un d'aquests dos formats:
    `{"field": ["message", ...]}` per a problemes a nivell de camp, o
    `{"detail": "message"}` per a errors de regles de negoci. Alguns validadors
    (robustesa de la contrasenya en registrar-se, caducitat del codi en
    verificar el correu) responen actualment amb una matriu simple `["message"]`
    en lloc del format amb clau de camp -- es tracta d'una inconsistència
    coneguda del servidor, de manera que el codi del client hauria d'acceptar
    ambdós formats.

    - Els errors d'autenticació es retornen com a `{"detail": "..."}` amb HTTP
    `401` (token de portador no vàlid) o `403` (manca el token de portador /
    privilegis insuficients).

    - Les respostes de límit de freqüència inclouen un camp `wait` amb el temps
    d'espera en segons.
servers:
  - url: https://apx.didit.me/auth/v2
    description: Servidor d'autenticació de producció
security: []
tags:
  - name: Programmatic Auth
    description: >-
      Cicle de vida del compte amb correu electrònic i contrasenya: registre,
      verificació, inici de sessió. Retorna el `access_token` JWT que utilitzes
      amb els endpoints de Gestió de comptes, a més (en verificar) del
      `client_id` i la `api_key` de la teva primera aplicació.
  - name: Account Management
    description: >-
      Endpoints autenticats (Bearer JWT) que llisten organitzacions i creen,
      obtenen o actualitzen aplicacions. Utilitza'ls per recuperar o rotar la
      `api_key` amb la qual autentiques les crides a l'API de verificació.
paths:
  /programmatic/register/:
    post:
      tags:
        - Programmatic Auth
      summary: Registra el compte
      description: >-
        Pas 1 de l'alta programàtica. Crea un compte pendent i envia un codi de
        6 caràcters per correu electrònic (TTL de 10 min). L'adreça es comprova
        abans de crear cap compte: una que no pugui rebre el codi retorna 400
        `email_undeliverable`. Límits de freqüència: 5/IP/hora, més un
        pressupost horari compartit per xarxa (/24 per a IPv4, /64 per a IPv6).
      operationId: programmatic_register
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
            examples:
              Gmail:
                summary: Registra't amb un compte personal de Gmail
                value:
                  email: you@yourdomain.com
                  password: MyStr0ng!Pass
              Work:
                summary: Registra't amb un correu electrònic professional
                value:
                  email: you@yourcompany.com
                  password: C0mplex#Pass1
      responses:
        '201':
          description: >-
            Registre completat amb èxit. S'ha enviat per correu electrònic un
            codi de verificació alfanumèric de 6 caràcters (p. ex., `A3K9F2`) a
            l'adreça proporcionada i és vàlid durant 10 minuts. A continuació,
            crida `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: >-
            Error de validació. L'embolcall previst és `{"field": ["..."]}` per
            a errors a nivell de camp i `{"detail": "..."}` per a errors de
            regles de negoci (per exemple, correu electrònic duplicat).
            Actualment, les regles de robustesa de la contrasenya responen amb
            una matriu simple `["..."]`, una regla cada vegada (una
            inconsistència coneguda del servidor; tracta-la com a `{"password":
            ["..."]}` fins que se solucioni). Quan l'adreça no pot rebre el codi
            (domini d'un sol ús, reservat o de prova, sense servidor de correu,
            una probable errada tipogràfica o una adreça que ha rebotat
            anteriorment), el cos és `EmailUndeliverableError` amb `code:
            "email_undeliverable"`; no es crea ni es modifica cap compte.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - $ref: '#/components/schemas/EmailUndeliverableError'
              examples:
                MissingFields:
                  summary: Cos buit
                  value:
                    email:
                      - This field is required.
                    password:
                      - This field is required.
                InvalidEmail:
                  summary: Correu electrònic amb format incorrecte
                  value:
                    email:
                      - Enter a valid email address.
                PasswordTooShort:
                  summary: Contrasenya de menys de 8 caràcters
                  value:
                    password:
                      - Ensure this field has at least 8 characters.
                PasswordMissingUppercase:
                  summary: Falta una lletra majúscula a la contrasenya
                  value:
                    - Password must contain at least one uppercase letter.
                PasswordMissingLowercase:
                  summary: Falta una lletra minúscula a la contrasenya
                  value:
                    - Password must contain at least one lowercase letter.
                PasswordMissingDigit:
                  summary: Falta un dígit a la contrasenya
                  value:
                    - Password must contain at least one digit.
                PasswordMissingSpecial:
                  summary: Falta un caràcter especial a la contrasenya
                  value:
                    - >-
                      Password must contain at least one special character
                      (!@#$%^&*()_+-=[]{}|;:,.<>?).
                Duplicate:
                  summary: El correu electrònic ja té un compte associat
                  value:
                    detail: An account with this email already exists.
                EmailUndeliverable:
                  summary: >-
                    L'adreça no pot rebre correus electrònics (domini d'un sol
                    ús)
                  value:
                    detail: >-
                      This email can't receive messages. Please use a different
                      email address.
                    code: email_undeliverable
                    reason: disposable_domain
                EmailLikelyTypo:
                  summary: Probable error tipogràfic al domini
                  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: >-
            Límit de freqüència assolit. S'han fet més de 5 intents de registre
            des de la mateixa IP en la darrera hora, o bé s'ha esgotat el
            pressupost horari de la xarxa del sol·licitant (/24 per a IPv4, /64
            per a IPv6, compartit entre registre i reenviament de codis). Tots
            dos casos inclouen `Retry-After: 3600`. També es retorna, amb una
            capçalera `Retry-After: 5`, quan el servei està comprovant
            momentàniament el màxim nombre de contrasenyes o codis possibles
            alhora; reintenta-ho després del nombre de segons indicat.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
              examples:
                RateLimited:
                  value:
                    detail: Too many registration attempts. Please try again later.
                PasswordChecksBusy:
                  summary: Massa comprovacions de contrasenya en curs
                  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: >-
            Qualsevol adreça de correu electrònic vàlida (personal, de feina,
            àlies). S'utilitza com a identificador únic del compte.
          example: you@yourdomain.com
        password:
          type: string
          minLength: 8
          description: >-
            Mínim 8 caràcters. Ha de contenir com a mínim una lletra majúscula
            (`A-Z`), una lletra minúscula (`a-z`), un dígit (`0-9`) i un
            caràcter especial de `!@#$%^&*()_+-=[]{}|;:,.<>?`. La validació
            informa d'una regla que ha fallat a la vegada.
          example: MyStr0ng!Pass
    RegisterResponse:
      type: object
      properties:
        message:
          type: string
          description: Confirmació fàcil de llegir que el codi de verificació s'ha enviat.
          example: Registration successful. Check your email for the verification code.
        email:
          type: string
          format: email
          description: El correu electrònic al qual s'ha enviat el codi de verificació.
          example: you@yourdomain.com
    ValidationError:
      description: >-
        Cos de l'error de validació. L'embolcall previst és un mapa `{field:
        ["message", ...]}` per a errors a nivell de camp o un embolcall d'una
        sola clau `{detail: "..."}` per a errors de regles de negoci. Uns quants
        validadors (força de la contrasenya durant el registre, validesa del
        codi a verify-email) responen actualment amb una matriu simple
        `["message"]` -- una inconsistència coneguda del costat del servidor.
        L'esquema següent manté aquesta branca de matriu simple perquè el codi
        client generat a partir d'aquesta especificació deserialitzi les
        respostes actuals, però el nou codi client l'hauria de tractar com el
        format amb clau de camp rellevant (`{password: [...]}` o `{code:
        [...]}`) i el contracte del servidor convergirà cap a aquesta forma.
      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: >-
        Retornat per `POST /programmatic/register/` quan l'adreça no pot rebre
        el codi de verificació. La comprovació s'executa abans de crear o
        modificar cap compte, de manera que no queda res creat.
      required:
        - detail
        - code
        - reason
      properties:
        detail:
          type: string
          description: Missatge fàcil de llegir.
          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: >-
            Per què s'ha rebutjat l'adreça: `invalid_address` (no és una adreça
            vàlida), `reserved_domain` (un domini reservat o de prova com ara
            `example.com`), `no_mail_records` (el domini no té servidor de
            correu), `disposable_domain` (un proveïdor de bústies d'un sol ús),
            `possible_typo` (un possible error tipogràfic d'un proveïdor comú;
            consulta `suggestion`), `suppressed` (l'adreça ha rebotat o ha
            generat una queixa anteriorment).
        suggestion:
          type: string
          description: >-
            El domini que probablement es pretenia utilitzar, present només quan
            el domini sembla un error tipogràfic (per exemple, `gmail.com` en
            lloc de `gmial.com`). L'API no accepta cap confirmació: registra't
            de nou amb l'adreça corregida.
          example: gmail.com
    RateLimitError:
      type: object
      description: >-
        Resposta de límit de freqüència o de bloqueig progressiu. `wait` és el
        temps d'espera en segons.
      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.