> ## 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 API 자격 증명 받기

> POST /programmatic/verify-email/을 호출해 이메일을 인증하고 Didit access token, client_id, api_key를 받으세요. 에이전트 네이티브 온보딩, 종량제 요금.



이메일 인증 및 자격 증명 받기 프롬프트
        프롬프트를 클립보드에 복사



      
      

\<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 ko/openapi-auth.json POST /programmatic/verify-email/
openapi: 3.0.0
info:
  version: 1.0.0
  title: Didit Auth API
  description: >-
    개발자와 AI 에이전트를 위한 프로그래밍 방식 등록 및 인증 API입니다. 브라우저 없이 API 호출 2번만으로 등록할 수 있습니다.
    에이전트 친화성이 가장 뛰어난 신원 인증 플랫폼입니다.


    ## 기본 URL


    이 사양의 모든 endpoint는 `https://apx.didit.me/auth/v2`에서 호스팅됩니다. 이는 인증
    API(`https://verification.didit.me/v3`)와는 다른 호스트입니다. 혼동하지 않도록 유의하십시오. 이 인증
    호스트는 **JWT 액세스 토큰**을 발급하며 **조직** 및 **애플리케이션**을 나열하고 관리할 수 있도록 합니다. 인증 호스트는 이
    API가 반환한 **`api_key`**로 인증하여 세션, 워크플로, AML 등을 호출하는 곳입니다.


    ## 인증 흐름 작동 방식


    1. `POST /programmatic/register/` — 이메일 + 비밀번호 제출.

    2. 이메일로 6자리 영숫자 코드 수신.

    3. `POST /programmatic/verify-email/` — 코드 제출. JWT `access_token`,
    `refresh_token`, 조직, 그리고 `client_id` + `api_key`가 포함된 기본 애플리케이션을 반환받습니다.

    4. `api_key`를 저장합니다. `https://verification.didit.me/v3/...`에 대한 모든 호출에
    `x-api-key`로 사용하십시오.

    5. 향후 다른 머신에서 `POST /programmatic/login/`으로 이메일 + 비밀번호를 새 JWT로 교환한 다음, `GET
    /organizations/me/` 및 애플리케이션 endpoint를 호출하여 자격 증명을 복구하거나 교체할 수 있습니다.


    JWT는 이 사양의 **계정 관리** endpoint에만 필요합니다. 인증 API 트래픽은 JWT가 아닌 장기 유효 `api_key`를
    사용합니다.


    ## 규칙


    - 모든 요청 및 응답 본문은 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"]`로 응답합니다. 이는 서버 측의 알려진 불일치 사항이므로 클라이언트 코드가 두 형태를 모두 수용하도록 작성해야
    합니다.

    - 인증 오류는 HTTP `401`(유효하지 않은 Bearer 토큰) 또는 `403`(Bearer 토큰 누락 / 권한 부족)과 함께
    `{"detail": "..."}` 형태로 반환됩니다.

    - 속도 제한 응답에는 대기 시간을 초 단위로 나타내는 `wait` 필드가 포함됩니다.
servers:
  - url: https://apx.didit.me/auth/v2
    description: 프로덕션 인증 서버
security: []
tags:
  - name: Programmatic Auth
    description: >-
      이메일 및 비밀번호 계정 라이프사이클: 가입, 인증, 로그인. 계정 관리 endpoint에 사용할 JWT `access_token`과
      (인증 완료 시) 첫 번째 애플리케이션의 `client_id` 및 `api_key`를 반환합니다.
  - name: Account Management
    description: >-
      조직 목록을 조회하고 애플리케이션을 생성, 조회 또는 업데이트하는 인증된 endpoint(JWT bearer)입니다. 검증 API
      호출에 인증하는 데 사용하는 `api_key`를 복구하거나 교체할 때 사용하십시오.
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: >-
            이메일이 인증되었습니다. 응답에는 이 인증 API용 token과 새로 생성된 애플리케이션의 `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: >-
            RS256 서명 JWT입니다. `apx.didit.me/auth/v2`의 계정 관리 endpoint에 대해
            `Authorization: Bearer <token>`으로 사용하십시오.
        refresh_token:
          type: string
          description: 액세스 token과 쌍을 이루는 리프레시 token입니다.
        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: >-
            모든 인증 API 호출 시 `x-api-key`로 사용합니다. 새 키는 `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.