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

# Verificació de correu electrònic API: credencials Didit

> POST /programmatic/verify-email/ per confirmar el correu i rebre tokens d'accés, client_id i api_key a Didit. Alta nativa per a agents i preu per ús.



Indicació per verificar el correu electrònic i obtenir les credencials
        Copia el prompt al porta-retalls



      
      

\<pre>

\`Exchange the email verification code for usable Didit credentials — step 2 of programmatic onboarding.

Endpoint:
POST https://apx.didit.me/auth/v2/programmatic/verify-email/

Authentication:
None. The email + code pair is the credential.

Request body:
\- email (string, required) — Same email used in /programmatic/register/.
\- code (string, required) — 6-character alphanumeric code from the registration email (e.g. "A3K9F2"). Valid for 15 minutes.

curl example:
curl -X POST https://apx.didit.me/auth/v2/programmatic/verify-email/ \
-H "Content-Type: application/json" \
-d '{
"email": "you@yourdomain.com",
"code": "A3K9F2"
}'

Response (200 OK):
\{
"access_token": "eyJ...RS256 JWT",
"refresh_token": "eyJ...RS256 JWT",
"expires_in": 86400,
"organization": {
"uuid": "a1b2c3d4-5678-...",
"name": "you"
},
"application": {
"uuid": "b2c3d4e5-6789-...",
"name": "you",
"client_id": "S9LIYGSoWNuGMLHsvEt9dQ",
"api_key": "sk_live_example_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"data_location": "eu"
}
}

What happens server-side:
1\. The pending account is marked email-verified.
2\. A default organization is created (named after the local part of the email, e.g. "you" from "you@yourdomain.com").
3\. A default application is created inside the organization with a fresh client_id and api_key, in the European Union (data_location "eu"). Its location can be chosen once with PATCH /organizations/me/{org_id}/applications/{app_id}/ before the application is used; see /auth-api/update-application.
4\. JWTs are issued (RS256, default 24h / 86400 seconds lifetime).

How to use the response:
\- application.api_key → set as the x-api-key header on EVERY call to https://verification.didit.me/v3/... (sessions, workflows, questionnaires, billing, etc.). PERSIST IT SECURELY. You can read it again later with GET /organizations/me/{org_id}/applications/{app_id}/.
\- access_token → use as "Authorization: Bearer <access_token>" against Account Management endpoints on https://apx.didit.me/auth/v2 (e.g. to create more applications).
\- refresh_token → exchange for a new access_token after expiry.

Save the api_key, the organization.uuid (org_id), and the application.uuid (app_id) — you will need all three to manage applications later.

Failure modes (400 unless noted):
\- Field-level: { "email": ["Enter a valid email address."] } or { "code": ["Ensure this field has at least 6 characters."] }.
\- Wrong or expired code CURRENTLY returns a BARE ARRAY ["Invalid or expired verification code."] — known server-side inconsistency; treat as { "code": [...] } client-side.
\- Unknown email: { "detail": "User not found." }

Recovery if you lose the api_key later:
Call POST /programmatic/login/ with email + password to get a fresh access_token, then GET /organizations/me/{org_id}/applications/{app_id}/ to read the api_key back. See /auth-api/login and /auth-api/get-credentials.

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/verify-email/
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/verify-email/:
    post:
      tags:
        - Programmatic Auth
      summary: Verifica el correu electrònic i emet credencials
      description: >-
        Pas 2 de l'alta. Canvia el codi de 6 caràcters per un compte verificat,
        una organització i aplicació per defecte, i un parell de JWT. Guarda el
        camp `api_key` retornat.
      operationId: programmatic_verify_email
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyEmailRequest'
            examples:
              Default:
                summary: Envia el codi del correu electrònic de registre
                value:
                  email: you@yourdomain.com
                  code: A3K9F2
      responses:
        '200':
          description: >-
            Correu electrònic verificat. La resposta conté tokens per a aquesta
            API d'autenticació a més del `client_id` i la `api_key` de la nova
            aplicació. Guarda la `api_key` de manera segura: és la credencial de
            llarga durada que utilitza cada crida a l'API de verificació.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyEmailResponse'
              examples:
                Success:
                  value:
                    access_token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
                    refresh_token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
                    expires_in: 86400
                    organization:
                      uuid: a1b2c3d4-5678-90ab-cdef-111111111111
                      name: developer
                    application:
                      uuid: b2c3d4e5-6789-01bc-defg-222222222222
                      name: developer
                      client_id: S9LIYGSoWNuGMLHsvEt9dQ
                      api_key: sk_live_example_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
                      data_location: eu
        '400':
          description: >-
            Error de validació. L'embolcall previst és `{"field": ["..."]}` per
            a problemes a nivell de camp i `{"detail": "..."}` per a errors de
            regles de negoci (per exemple, usuari no trobat). Els errors de codi
            incorrecte o caducat responen actualment amb una matriu simple
            `["Invalid or expired verification code."]` (una inconsistència
            coneguda del servidor; tracta-la com a `{"code": ["..."]}` fins que
            se solucioni).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              examples:
                MissingFields:
                  summary: Cos buit
                  value:
                    email:
                      - This field is required.
                    code:
                      - This field is required.
                CodeTooShort:
                  summary: Codi de menys de 6 caràcters
                  value:
                    code:
                      - Ensure this field has at least 6 characters.
                InvalidEmail:
                  summary: Correu electrònic amb format incorrecte
                  value:
                    email:
                      - Enter a valid email address.
                InvalidCode:
                  summary: Codi incorrecte o caducat
                  value:
                    - Invalid or expired verification code.
                UserNotFound:
                  summary: No hi ha cap compte pendent per a aquest correu electrònic
                  value:
                    detail: User not found.
        '429':
          description: >-
            El servei està comprovant momentàniament tantes contrasenyes o codis
            com pot alhora. S'envia amb una capçalera `Retry-After: 5`;
            reintenta-ho després del nombre de segons indicat.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
              examples:
                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/verify-email/
            \
              -H "Content-Type: application/json" \
              -d '{
                "email": "you@yourdomain.com",
                "code": "A3K9F2"
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

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

            result = client.account.verify_email(
                email="you@yourdomain.com",
                code="A3K9F2",
            )
            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.verifyEmail({
              email: "you@yourdomain.com",
              code: "A3K9F2",
            });
            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.VerifyEmail(ctx, didit.VerifyEmailRequest{\n\tEmail: \"you@yourdomain.com\",\n\tCode:  \"A3K9F2\",\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.VerifyEmailRequest;


            // This call needs no API key.

            Didit client = new Didit();


            var result =
            client.account().verifyEmail(VerifyEmailRequest.builder()
                    .email("you@yourdomain.com")
                    .code("A3K9F2")
                    .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->verifyEmail([
                'email' => 'you@yourdomain.com',
                'code' => 'A3K9F2',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

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

            result = didit.account.verify_email(
              email: "you@yourdomain.com",
              code: "A3K9F2"
            )
            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.VerifyEmailAsync(new
            VerifyEmailRequest

            {
                Email = "you@yourdomain.com",
                Code = "A3K9F2",
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    VerifyEmailRequest:
      type: object
      required:
        - email
        - code
      properties:
        email:
          type: string
          format: email
          description: Correu electrònic utilitzat durant `POST /programmatic/register/`.
          example: you@yourdomain.com
        code:
          type: string
          minLength: 6
          maxLength: 6
          description: >-
            Codi alfanumèric de 6 caràcters del correu electrònic de
            verificació. Els codis caduquen 10 minuts després d'haver enviat el
            codi més recent.
          example: A3K9F2
    VerifyEmailResponse:
      type: object
      properties:
        access_token:
          type: string
          description: >-
            JWT signat amb RS256. Utilitza'l com a `Authorization: Bearer
            <token>` per als endpoints de gestió de comptes a
            `apx.didit.me/auth/v2`.
        refresh_token:
          type: string
          description: Token d'actualització vinculat amb el token d'accés.
        expires_in:
          type: integer
          description: Temps de vida del token d'accés en segons (per defecte 86400).
          example: 86400
        organization:
          $ref: '#/components/schemas/OrganizationSummary'
        application:
          $ref: '#/components/schemas/ApplicationCredentialsSummary'
    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.
    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.
    OrganizationSummary:
      type: object
      description: >-
        Estructura mínima de l'organització inclosa directament a la resposta
        per `POST /programmatic/verify-email/`.
      properties:
        uuid:
          type: string
          format: uuid
          example: a1b2c3d4-5678-90ab-cdef-111111111111
        name:
          type: string
          example: developer
    ApplicationCredentialsSummary:
      type: object
      description: >-
        Estructura mínima de l'aplicació inclosa directament a la resposta de
        `POST /programmatic/verify-email/`. Desa la `api_key` immediatament.
      properties:
        uuid:
          type: string
          format: uuid
          example: b2c3d4e5-6789-01bc-defg-222222222222
        name:
          type: string
          example: developer
        client_id:
          type: string
          example: S9LIYGSoWNuGMLHsvEt9dQ
        api_key:
          type: string
          description: >-
            Utilitza això com a `x-api-key` a cada crida a l'API de verificació.
            Les claus noves comencen amb `sk_live_` (aplicació de producció) o
            `sk_test_` (aplicació sandbox), seguides de 43 caràcters segurs per
            a URL (lletres, dígits, `-` i `_`). Les claus creades abans d'aquest
            format no tenen prefix i continuen funcionant sense canvis.
          example: sk_live_example_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        data_location:
          $ref: '#/components/schemas/ApplicationDataLocation'
    ApplicationDataLocation:
      type: string
      enum:
        - eu
        - au
        - mx
      description: >-
        On s'emmagatzemen i es processen les dades de verificació de
        l'aplicació, que se selecciona en crear l'aplicació. `eu` és la Unió
        Europea (Irlanda), l'opció per defecte. `au` (Austràlia, Sydney) i `mx`
        (Mèxic) estaran disponibles properament: una sol·licitud que els indiqui
        respon 400 `This data location is not available yet.` L'aplicació de
        sandbox d'una organització sempre és a la Unió Europea.
      example: eu

````

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