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

# API التحقق من البريد الإلكتروني: بيانات اعتماد Didit

> أكّد البريد الإلكتروني عبر POST /programmatic/verify-email/ واحصل على رموز الوصول وclient_id وapi_key من Didit. تسجيل للوكلاء، ودفع حسب الاستخدام.



موجّه التحقق من البريد الإلكتروني والحصول على بيانات الاعتماد
        نسخ الموجّه إلى الحافظة



      
      

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



      
      

الصق في



## OpenAPI

````yaml ar/openapi-auth.json POST /programmatic/verify-email/
openapi: 3.0.0
info:
  version: 1.0.0
  title: Didit Auth API
  description: >-
    واجهة برمجة تطبيقات (API) للتسجيل والمصادقة البرمجية للمطورين ووكلاء الذكاء
    الاصطناعي. سجّل من خلال استدعاءين فقط لـ API - دون الحاجة إلى متصفح. منصة
    التحقق من الهوية الأكثر ملاءمة للوكلاء.


    ## عنوان URL الأساسي


    تتم استضافة جميع endpoint في هذه المواصفات على
    `https://apx.didit.me/auth/v2`. هذا المضيف مختلف عن API التحقق
    (`https://verification.didit.me/v3`). ميّز بينهما جيداً: يُصدر مضيف المصادقة
    هذا **رموز وصول JWT** الخاصة بك ويسمح لك بسرد وإدارة **المؤسسات**
    و**التطبيقات** التابعة لك. أما مضيف التحقق فهو المكان الذي تستدعي فيه
    الجلسات، وسير العمل، وفحص AML، وما إلى ذلك، بعد المصادقة باستخدام
    **`api_key`** المُرجع بواسطة هذه الـ API.


    ## طريقة عمل تدفق المصادقة


    1. `POST /programmatic/register/` - إرسال البريد الإلكتروني + كلمة المرور.

    2. استلام رمز مكوّن من 6 أحرف وأرقام عبر البريد الإلكتروني.

    3. `POST /programmatic/verify-email/` - إرسال الرمز. ستحصل في المقابل على
    `access_token` الخاص بـ JWT، و`refresh_token`، ومؤسسة، وتطبيق افتراضي يحتوي
    على `client_id` + `api_key`.

    4. احفظ `api_key`. واستخدمه كـ `x-api-key` لكل استدعاء إلى
    `https://verification.didit.me/v3/...`.

    5. من أي جهاز مستقبلاً، يتيح لك `POST /programmatic/login/` استبدال بريدك
    الإلكتروني + كلمة المرور بـ JWT جديد، ثم استدعِ `GET /organizations/me/` و
    endpoint الخاصة بالتطبيق لاستعادة بيانات الاعتماد أو تدويرها.


    لا يلزم JWT إلا لـ endpoint الخاصة بـ **إدارة الحساب** في هذه المواصفات؛
    وتستخدم حركة مرور API التحقق `api_key` طويل الأجل، وليس JWT.


    ## الاصطلاحات


    - جميع نصوص الطلب والاستجابة بتنسيق JSON (`Content-Type: application/json`).

    - **استخدم عنوان بريد إلكتروني حقيقي وقابل للاستلام عند اختبار `POST
    /programmatic/register/`.** يرسل endpoint رمز التحقق بشكل متزامن، لذا فإن
    العناوين الموجودة على نطاقات الاختبار المحجوزة (`@example.com`،
    و`@example.org`، و`@*.test`، و`@*.example`، و`@*.invalid`) تُرفض عند تسليم
    البريد ويعود الطلب بالرمز `500`. استبدل العنصر النائب `you@yourdomain.com`
    في الأمثلة بصندوق بريد وارد يمكنك قراءته فعلياً.

    - تعيد أخطاء التحقق من الصحة رمز الحالة HTTP `400` بإحدى صيغتين: `{"field":
    ["message", ...]}` للمشكلات على مستوى الحقول، أو `{"detail": "message"}`
    لأخطاء قواعد العمل. وترد قلة من أدوات التحقق من الصحة (قوة كلمة المرور عند
    التسجيل، وانتهاء صلاحية الرمز عند التحقق من البريد الإلكتروني) حالياً
    بمصفوفة مجردة `["message"]` بدلاً من الصيغة المحددة بمفتاح الحقل - وهو
    اختلاف معروف من جانب الخادم، لذا يجب أن يقبل كود العميل كلا الشكلين.

    - تعود أخطاء المصادقة على هيئة `{"detail": "..."}` مع HTTP `401` (رمز الحامل
    غير صالح) أو `403` (رمز الحامل مفقود / صلاحيات غير كافية).

    - تتضمن استجابات حد المعدل حقلاً باسم `wait` يحدد فترة الانتظار بالثواني.
servers:
  - url: https://apx.didit.me/auth/v2
    description: خادم مصادقة الإنتاج
security: []
tags:
  - name: Programmatic Auth
    description: >-
      دورة حياة الحساب بالبريد الإلكتروني وكلمة المرور: التسجيل، والتحقق، وتسجيل
      الدخول. يُرجع `access_token` الخاص بـ JWT الذي تستخدمه مع endpoints إدارة
      الحساب، بالإضافة إلى (عند التحقق) `client_id` و`api_key` لتطبيقك الأول.
  - name: Account Management
    description: >-
      الـ endpoints المُصادق عليها (JWT bearer) التي تعرض المؤسسات وتُنشئ
      التطبيقات أو تجلبها أو تُحدّثها. استخدم هذه الـ endpoints لاسترداد أو
      تدوير `api_key` الذي تستخدمه لمصادقة استدعاءات API للتحقق.
paths:
  /programmatic/verify-email/:
    post:
      tags:
        - Programmatic Auth
      summary: التحقق من البريد الإلكتروني وإصدار بيانات الاعتماد
      description: >-
        الخطوة 2 من التسجيل. تستبدل الرمز المكون من 6 أحرف بحساب تم التحقق منه،
        ومؤسسة وتطبيق افتراضيين، وزوج JWT. احتفظ بـ `api_key` المُرجع.
      operationId: programmatic_verify_email
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyEmailRequest'
            examples:
              Default:
                summary: إرسال الرمز المستلم من بريد التسجيل الإلكتروني
                value:
                  email: you@yourdomain.com
                  code: A3K9F2
      responses:
        '200':
          description: >-
            تم التحقق من البريد الإلكتروني. تحتوي الاستجابة على رموز token لـ
            API المصادقة هذا بالإضافة إلى `client_id` و`api_key` للتطبيق الجديد
            كلياً. احفظ `api_key` بشكل آمن — فهو بيانات الاعتماد طويلة الأجل
            المستخدمة في كل استدعاء لـ API التحقق.
          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: >-
            خطأ في التحقق. الغلاف المقصود هو `{"field": ["..."]}` للمشكلات على
            مستوى الحقول و`{"detail": "..."}` لأخطاء قواعد العمل (مثل عدم العثور
            على المستخدم). تستجيب أخطاء الرمز غير الصحيح أو المنتهي الصلاحية
            حالياً بمصفوفة مجردة `["Invalid or expired verification code."]` --
            وهو تناقض معروف من جانب الخادم؛ تعامل معها كـ `{"code": ["..."]}`
            حتى يتم إصلاحها.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              examples:
                MissingFields:
                  summary: نص الطلب فارغ
                  value:
                    email:
                      - This field is required.
                    code:
                      - This field is required.
                CodeTooShort:
                  summary: الرمز أقل من 6 أحرف
                  value:
                    code:
                      - Ensure this field has at least 6 characters.
                InvalidEmail:
                  summary: بريد إلكتروني غير صالح
                  value:
                    email:
                      - Enter a valid email address.
                InvalidCode:
                  summary: رمز خاطئ أو منتهي الصلاحية
                  value:
                    - Invalid or expired verification code.
                UserNotFound:
                  summary: لا يوجد حساب قيد الانتظار لهذا البريد الإلكتروني
                  value:
                    detail: User not found.
        '429':
          description: >-
            تقوم الخدمة حالياً بالتحقق من أكبر عدد ممكن من كلمات المرور أو
            الرموز في الوقت نفسه. يتم إرسالها مع الرأس `Retry-After: 5`؛ أعد
            المحاولة بعد عدد الثواني المحدد.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
              examples:
                PasswordChecksBusy:
                  summary: هناك عمليات فحص لكلمة المرور قيد التنفيذ أكثر من اللازم
                  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: البريد الإلكتروني المستخدم أثناء `POST /programmatic/register/`.
          example: you@yourdomain.com
        code:
          type: string
          minLength: 6
          maxLength: 6
          description: >-
            رمز أبجدي رقمي مكوّن من 6 أحرف من بريد التحقق الإلكتروني. تنتهي
            صلاحية الرموز بعد 10 دقائق من إرسال أحدث رمز.
          example: A3K9F2
    VerifyEmailResponse:
      type: object
      properties:
        access_token:
          type: string
          description: >-
            JWT موقّع باستخدام RS256. يُستخدم كـ `Authorization: Bearer <token>`
            لنقاط endpoint لإدارة الحسابات على `apx.didit.me/auth/v2`.
        refresh_token:
          type: string
          description: رمز التحديث المقترن برمز الوصول.
        expires_in:
          type: integer
          description: مدة صلاحية token الوصول بالثواني (الافتراضي 86400).
          example: 86400
        organization:
          $ref: '#/components/schemas/OrganizationSummary'
        application:
          $ref: '#/components/schemas/ApplicationCredentialsSummary'
    ValidationError:
      description: >-
        جسم خطأ التحقق من الصحة. الغلاف المقصود هو خريطة `{field: ["message",
        ...]}` للأخطاء على مستوى الحقول أو غلاف بمفتاح فردي `{detail: "..."}`
        لأخطاء قواعد العمل. هناك عدد قليل من أدوات التحقق (قوة كلمة المرور عند
        التسجيل، وصلاحية الرمز عند verify-email) تستجيب حالياً بمصفوفة مجردة
        `["message"]` -- وهو تعارض معروف من جانب الخادم. يحتفظ المخطط أدناه بفرع
        المصفوفة المجردة حتى تتمكن التعليمات البرمجية للعميل المنشأة من هذه
        المواصفة من إلغاء تسلسل استجابات اليوم، ولكن يجب أن تعامل التعليمات
        البرمجية الجديدة للعميل هذه الاستجابة بالشكل المخصص للحقل المعني
        (`{password: [...]}` أو `{code: [...]}`) وسيتقارب عقد الخادم مع هذا
        الشكل.
      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: استجابة حد المعدل أو الحظر التدريجي. يمثل `wait` فترة التهدئة بالثواني.
      properties:
        detail:
          type: string
          example: >-
            Too many login attempts from this IP address. Please wait before
            trying again.
    OrganizationSummary:
      type: object
      description: >-
        الهيكل الأدنى للمؤسسة المُعاد ضمن الاستجابة مباشرة عبر `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: >-
        الهيكل الأدنى للتطبيق المُعاد ضمن الاستجابة مباشرة عبر `POST
        /programmatic/verify-email/`. احفظ `api_key` على الفور.
      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: >-
            استخدم هذا كـ `x-api-key` في كل استدعاء لواجهة API للتحقق. تبدأ
            المفاتيح الجديدة بـ `sk_live_` (تطبيق الإنتاج) أو `sk_test_` (تطبيق
            البيئة التجريبية)، متبوعة بـ 43 حرفاً آمناً لعناوين URL (أحرف،
            أرقام، `-` و`_`). المفاتيح التي تم إنشاؤها قبل هذا التنسيق لا تحتوي
            على بادئة وتستمر في العمل دون تغيير.
          example: sk_live_example_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        data_location:
          $ref: '#/components/schemas/ApplicationDataLocation'
    ApplicationDataLocation:
      type: string
      enum:
        - eu
        - au
        - mx
      description: >-
        مكان تخزين ومعالجة بيانات التحقق الخاصة بالتطبيق، ويتم اختياره عند إنشاء
        التطبيق. القيمة `eu` هي الاتحاد الأوروبي (أيرلندا)، وهو الخيار
        الافتراضي. ستتوفر قيمتا `au` (أستراليا، سيدني) و`mx` (المكسيك) قريباً:
        أي طلب يحددهما يُرجع استجابة 400 `This data location is not available
        yet.`. يكون تطبيق البيئة التجريبية للمؤسسة دائماً في الاتحاد الأوروبي.
      example: eu

````

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