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

# واجهة برمجة تطبيقات المصادقة: التسجيل البرمجي

> أنشئ مؤسسات Didit برمجياً عبر واجهة Auth API. مصممة للوكلاء الأذكياء دون متصفح. ابنِ بنية KYC للحسابات الفرعية، بالدفع لكل استدعاء، دون عقود.



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



      
      

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



      
      

الصق في



## OpenAPI

````yaml ar/openapi-auth.json POST /programmatic/register/
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/register/:
    post:
      tags:
        - Programmatic Auth
      summary: تسجيل الحساب
      description: >-
        الخطوة 1 من التسجيل البرمجي. تنشئ حساباً معلقاً وترسل رمزاً مكوناً من 6
        أحرف عبر البريد الإلكتروني (صالح لمدة 10 دقائق). يتم فحص العنوان قبل
        إنشاء أي حساب: يؤدي العنوان الذي لا يمكنه تلقي الرمز إلى إرجاع 400
        `email_undeliverable`. حدود المعدل: 5 لكل IP في الساعة، بالإضافة إلى حد
        ساعي مشترك لكل شبكة (/24 لـ IPv4، و/64 لـ IPv6).
      operationId: programmatic_register
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
            examples:
              Gmail:
                summary: التسجيل باستخدام حساب Gmail شخصي
                value:
                  email: you@yourdomain.com
                  password: MyStr0ng!Pass
              Work:
                summary: التسجيل باستخدام بريد العمل الإلكتروني
                value:
                  email: you@yourcompany.com
                  password: C0mplex#Pass1
      responses:
        '201':
          description: >-
            تم التسجيل بنجاح. تم إرسال رمز تحقق أبجدي رقمي مكون من 6 خانات (مثل
            `A3K9F2`) عبر البريد الإلكتروني إلى العنوان المقدَّم، وهو صالح لمدة
            10 دقائق. قم باستدعاء `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: >-
            خطأ في التحقق. الغلاف المقصود هو `{"field": ["..."]}` للأخطاء على
            مستوى الحقول و`{"detail": "..."}` لأخطاء قواعد العمل (مثل تكرار
            البريد الإلكتروني). تستجيب قواعد قوة كلمة المرور حالياً بمصفوفة
            مجردة `["..."]`، قاعدة واحدة في كل مرة -- وهو تناقض معروف من جانب
            الخادم؛ تعامل معها كـ `{"password": ["..."]}` حتى يتم إصلاحها. عندما
            يتعذر على العنوان استلام الرمز (نطاق مخصص للاستخدام لمرة واحدة، أو
            محجوز، أو تجريبي، أو عدم وجود خادم بريد، أو خطأ إملائي محتمل، أو
            عنوان ارتدت منه الرسائل سابقاً)، يكون نص الاستجابة هو
            `EmailUndeliverableError` مع `code: "email_undeliverable"`؛ ولا يتم
            إنشاء أي حساب أو تعديله.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - $ref: '#/components/schemas/EmailUndeliverableError'
              examples:
                MissingFields:
                  summary: نص الطلب فارغ
                  value:
                    email:
                      - This field is required.
                    password:
                      - This field is required.
                InvalidEmail:
                  summary: بريد إلكتروني غير صالح
                  value:
                    email:
                      - Enter a valid email address.
                PasswordTooShort:
                  summary: كلمة المرور أقل من 8 أحرف
                  value:
                    password:
                      - Ensure this field has at least 8 characters.
                PasswordMissingUppercase:
                  summary: كلمة المرور ينقصها حرف كبير
                  value:
                    - Password must contain at least one uppercase letter.
                PasswordMissingLowercase:
                  summary: كلمة المرور ينقصها حرف صغير
                  value:
                    - Password must contain at least one lowercase letter.
                PasswordMissingDigit:
                  summary: كلمة المرور ينقصها رقم
                  value:
                    - Password must contain at least one digit.
                PasswordMissingSpecial:
                  summary: كلمة المرور ينقصها حرف خاص
                  value:
                    - >-
                      Password must contain at least one special character
                      (!@#$%^&*()_+-=[]{}|;:,.<>?).
                Duplicate:
                  summary: البريد الإلكتروني لديه حساب بالفعل
                  value:
                    detail: An account with this email already exists.
                EmailUndeliverable:
                  summary: لا يمكن للعنوان استلام البريد الإلكتروني (نطاق مؤقت)
                  value:
                    detail: >-
                      This email can't receive messages. Please use a different
                      email address.
                    code: email_undeliverable
                    reason: disposable_domain
                EmailLikelyTypo:
                  summary: خطأ إملائي محتمل في النطاق
                  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: >-
            تم تطبيق حد المعدل. أكثر من 5 محاولات تسجيل من نفس عنوان IP خلال
            الساعة الأخيرة، أو استنفاد الرصيد الساعي لشبكة المتصل (/24 لـ IPv4،
            و/64 لـ IPv6، المشترك بين التسجيل وإعادة إرسال الرموز). يحمل كلاهما
            الرأس `Retry-After: 3600`. يُرجع أيضاً مع الرأس `Retry-After: 5`
            عندما تكون الخدمة بصدد فحص أكبر عدد ممكن من كلمات المرور أو الرموز
            في الوقت ذاته؛ أعد المحاولة بعد عدد الثواني الموضح.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
              examples:
                RateLimited:
                  value:
                    detail: Too many registration attempts. Please try again later.
                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/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: >-
            أي عنوان بريد إلكتروني صالح (شخصي، عمل، اسم مستعار). يُستخدم كمعرّف
            فريد للحساب.
          example: you@yourdomain.com
        password:
          type: string
          minLength: 8
          description: >-
            8 أحرف كحد أدنى. يجب أن يحتوي على حرف كبير واحد على الأقل (`A-Z`)،
            وحرف صغير واحد على الأقل (`a-z`)، ورقم واحد على الأقل (`0-9`)، وحرف
            خاص واحد على الأقل من `!@#$%^&*()_+-=[]{}|;:,.<>?`. يُبلِغ التحقق عن
            قاعدة فاشلة واحدة في كل مرة.
          example: MyStr0ng!Pass
    RegisterResponse:
      type: object
      properties:
        message:
          type: string
          description: تأكيد سهل القراءة يفيد بأنه تم إرسال رمز التحقق.
          example: Registration successful. Check your email for the verification code.
        email:
          type: string
          format: email
          description: البريد الإلكتروني الذي أُرسل إليه رمز التحقق.
          example: you@yourdomain.com
    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.
    EmailUndeliverableError:
      type: object
      description: >-
        يتم إرجاعها بواسطة `POST /programmatic/register/` عندما يتعذر على
        العنوان تلقي رمز التحقق. يتم تشغيل الفحص قبل إنشاء أي حساب أو تغييره،
        لذلك لا يُترك أي أثر.
      required:
        - detail
        - code
        - reason
      properties:
        detail:
          type: string
          description: رسالة سهلة القراءة.
          example: >-
            This email can't receive messages. Please use a different email
            address.
        code:
          type: string
          enum:
            - email_undeliverable
          description: دائماً `email_undeliverable`.
        reason:
          type: string
          enum:
            - invalid_address
            - reserved_domain
            - no_mail_records
            - disposable_domain
            - possible_typo
            - suppressed
          description: >-
            سبب رفض العنوان: `invalid_address` (عنوان غير صالح)،
            `reserved_domain` (نطاق محجوز أو تجريبي مثل `example.com`)،
            `no_mail_records` (لا يحتوي النطاق على خادم بريد)،
            `disposable_domain` (مزود بريد مؤقت)، `possible_typo` (خطأ إملائي
            محتمل في اسم مزود شائع؛ انظر `suggestion`)، `suppressed` (ارتد
            البريد سابقاً من هذا العنوان أو تم تسجيل شكوى بشأنه).
        suggestion:
          type: string
          description: >-
            النطاق المقصود على الأرجح، ولا يظهر إلا عندما يبدو النطاق كخطأ
            إملائي (على سبيل المثال `gmail.com` بدلاً من `gmial.com`). لا تقبل
            API التأكيد: سجل مجدداً باستخدام العنوان المصحح.
          example: gmail.com
    RateLimitError:
      type: object
      description: استجابة حد المعدل أو الحظر التدريجي. يمثل `wait` فترة التهدئة بالثواني.
      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.