> ## 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 인증: 안전한 KYC API 요청 가이드

> Didit API 요청은 x-api-key 헤더의 범위 지정 키로 인증합니다. 잘못되거나 만료된 키는 401을, 키가 누락된 경우 403을 반환합니다.



API 인증 프롬프트
        프롬프트를 클립보드에 복사



      
      

\<pre>

\````# Goal — authenticate against Didit's REST API

Two hosts, two auth schemes. Never mix them up.

\## Host map

\| Host | Surface | Auth header |
\|---|---|---|
\| `https://verification.didit.me` | Verification API — sessions, workflows, entities, transactions, standalone APIs, lists, webhooks, billing (every `/v3/...` route) | `x-api-key: <DIDIT_API_KEY>` |
\| `https://apx.didit.me` | Account / organization / application management (`/auth/v2/programmatic/...`, `/auth/v2/organizations/...`) | `Authorization: Bearer <JWT access_token>` |

The verification API does **not** use OAuth Bearer tokens. It uses a long-lived API key on the `x-api-key` header. Treat the key as a server-side secret — never ship it to a browser or mobile bundle.

\## How to obtain the api_key (no console UI needed)

\<Warning>
Substitute `you@yourdomain.com` below with a real inbox. The register endpoint sends the verification code synchronously, so reserved test domains (`@example.com`, `@example.org`, `@*.test`, `@*.example`, `@*.invalid`) get refused by mail delivery and the call returns a `500`.
\</Warning>

\```bash
\# 1) Register — emails a 6-char code (15 min TTL).
\#    Password rules: ≥8 chars, 1 uppercase, 1 lowercase, 1 digit, 1 special.
curl -X POST https://apx.didit.me/auth/v2/programmatic/register/ \
-H "Content-Type: application/json" \
-d '{"email": "you@yourdomain.com", "password": "StrongP@ss1"}'

\# 2) Verify email — returns api_key inline.
curl -X POST https://apx.didit.me/auth/v2/programmatic/verify-email/ \
-H "Content-Type: application/json" \
-d '{"email": "you@yourdomain.com", "code": "A3K9F2"}'
\# 200 -> { access_token, refresh_token, organization, application: { api_key, client_id, uuid } }
\```

Persist `response.application.api_key` as the env var `DIDIT_API_KEY`.
New keys start with `sk_live_` (live application) or `sk_test_` (sandbox application), followed by 43 URL-safe characters.
Keys created before this format have no prefix and keep working, so never validate a key by its prefix.

\## Recover the key (lost it)

\```bash
\# Log back in to get a fresh JWT
TOK=$(curl -s -X POST https://apx.didit.me/auth/v2/programmatic/login/ \
-H "Content-Type: application/json" \
-d '{"email":"you@yourdomain.com","password":"StrongP@ss1"}' | jq -r .access_token)

\# Find your org and app
curl https://apx.didit.me/auth/v2/organizations/me/ -H "Authorization: Bearer $TOK"
curl https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/$APP_ID/ \
-H "Authorization: Bearer $TOK"
\# Response.api_key is your key.
\```

\## Calling the verification API

\```bash
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"workflow_id":"<WORKFLOW_ID>","vendor_data":"user-42","callback":"https://myapp.com/return"}'
\```

\## Failure modes

\| Status | Meaning | Fix |
\|---|---|---|
\| `401` on verification.didit.me | `x-api-key` header wrong, malformed, revoked or expired | Re-fetch via the recover-key flow above, or use a key that has not expired |
\| `403` on verification.didit.me | No `x-api-key` header, a scoped key without access to this resource or action, or a key called from an address outside its IP list | Use a key with that access (Developers -> API keys in the console) |
\| `403` with `"code": "application_deleted"` on verification.didit.me | The key's application was deleted. You get this for a few minutes after the deletion; after that the key is refused like any invalid key | Do not retry: the application and its keys no longer exist. Use a key of an application that exists |
\| `404` on a session route | The session is outside the scoped key's workflows or statuses | Use a key whose limits include that session |
\| `403` on apx.didit.me | JWT `Authorization` header missing or expired | Call `POST /auth/v2/programmatic/login/` again |
\| `429` | Rate limit; response includes a `wait` field (seconds) | Back off, then retry |

\## Sources of truth
\- /openapi-auth.json — every account / org / app endpoint
\- /openapi-25.json — every verification endpoint
\- /integration/integration-prompt — end-to-end integration recipe````

\</pre>



      
      

붙여넣을 곳

## API 키 확인하기Didit에서 API 키는 계정 내 특정 **애플리케이션**으로 범위가 지정됩니다. 애플리케이션은 특정 프로젝트 또는 환경에 맞게 워크플로를 구성하고 인증을 관리할 수 있는 작업 공간입니다.애플리케이션을 생성하면 전체 접근 권한을 가진 기본 API 키가 부여됩니다. 그 외에도 서비스나 파트너에 필요한 권한만 가진 추가 키를 생성할 수 있습니다. 키를 확인하는 방법은 다음과 같습니다:**1. Business Console에 로그인**[**Didit Business Console**](https://business.didit.me)로 이동하여 로그인합니다.**2. 애플리케이션 선택**상단 드롭다운 메뉴에서 작업할 **애플리케이션**을 선택합니다.**3. API 키 열기**왼쪽 사이드바에서 **Developers -> API keys**로 이동합니다.**4. 키 복사 또는 생성****기본** 키는 애플리케이션 자체의 비밀 키입니다. 서비스나 파트너에게 필요한 권한만 부여된 자체 비밀 키를 제공하려면 새 키를 생성하세요.> [!WARNING]
>
> **API 키는 비밀 정보이므로 비밀번호처럼 안전하게 다루어야 합니다.**
>
> 기본 키는 애플리케이션을 대신하여 API에 대한 전체 접근 권한을 제공합니다. 프론트엔드 코드, 공개 저장소 또는 클라이언트 측 번들에 절대 노출해서는 안 됩니다. 항상 서버 측에만 보관하세요.### API 키 형식새 API 키는 프로덕션 환경 애플리케이션의 경우 `sk_live_`, 샌드박스 애플리케이션의 경우 `sk_test_`로 시작하며, 그 뒤에 URL에서 사용할 수 있는 43개의 문자(영문자, 숫자, `-`, `_`)가 이어집니다.
이 형식 도입 이전에 생성된 키에는 접두사가 없으며 기존과 동일하게 계속 작동합니다.
접두사를 포함한 전체 키를 `x-api-key` 헤더로 전송해야 하며, 접두사가 없다는 이유로 키를 거부하지 마세요.## 조직 ID 확인하기**조직 ID**는 조직을 식별하는 UUID입니다. `/auth/v2/organizations/me/{org_id}/applications/`와 같이 조직 범위의 API 경로에서 사용합니다. API 호출 없이 Business Console에서 바로 복사할 수 있습니다:**1. 조직 설정 열기**[**Didit Business Console**](https://business.didit.me)에서 **조직 설정**으로 이동합니다.**2. 조직 ID 복사****조직 ID** 필드에는 조직 이름 옆에 조직의 UUID와 클립보드 복사 버튼이 표시됩니다.***## 인증된 요청 보내기API 요청을 인증하려면 비밀 API 키를 `x-api-key` HTTP 헤더에 포함하세요.다음은 `Create Session` endpoint에 대한 인증된 요청의 예시입니다:```shell cURL theme={null}
curl --request POST \
     --url https://verification.didit.me/v3/session/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR_API_KEY' \
     --data '
{
  "workflow_id": "WORKFLOW_ID",
  "vendor_data": "USER_ID",
  "callback": "CALLBACK_URL"
}
'
```***## 에러 처리API 키가 올바르지 않거나 형식이 잘못되었거나 취소된 경우, API는 `401 Unauthorized`를 반환합니다:```json theme={null}
{
  "detail": "Authentication credentials were not provided or are invalid."
}
```만료된 키 역시 `"detail": "This API key has expired."`와 함께 `401`을 반환합니다.
키가 없는 요청은 `"detail": "You do not have permission to perform this action."`과 함께 `403`을 반환합니다.| 상태 코드 | 의미 |
| - | - |
| **401** | API 키가 올바르지 않거나 형식이 잘못되었거나 취소되었거나 만료됨 |
| **403** | API 키가 전송되지 않았거나, 키에 요청한 리소스 또는 작업에 대한 권한이 없거나, 키의 IP 목록 외의 주소에서 요청이 수신됨 |
| `"code": "application_deleted"`가 포함된 **403** | 키가 삭제된 애플리케이션에 속해 있습니다. API는 삭제 후 몇 분 동안 이 응답을 반환한 다음, 유효하지 않은 키와 마찬가지로 키를 거부합니다. 애플리케이션과 해당 키가 더 이상 존재하지 않으므로 재시도하지 마세요. |
| **404** | 세션 경로의 경우: 세션이 키의 워크플로 또는 상태 범위를 벗어남 |[API 에러](https://docs.didit.me/ko/integration/api-errors.md) 페이지에 모든 상태, 본문 및 코드가 나열되어 있습니다.***## 범위 지정 API 키기본 키를 공유하는 대신 각 서비스나 파트너에 자체 키를 부여하세요.
각 키에는 고유한 접근 권한이 있습니다. 모든 리소스(세션, 결정, 미디어, 개인, 기업, 거래, 워크플로, webhook, 애플리케이션 설정, 분석)에 대해 없음, 읽기 또는 쓰기 권한을 설정할 수 있으며, 특정 워크플로, 승인된 세션만, IP 주소 목록 및 만료일로 선택적 제한을 둘 수 있습니다.
24시간의 중복 기간을 두고 키를 교체할 수 있으며, 즉시 취소할 수도 있습니다.범위 지정 접근 기능이 도입되기 전에 생성된 키는 전체 접근 권한을 유지합니다.사전 설정, 각 항목이 다루는 리소스, API가 범위 지정 키에 응답하는 방식에 대한 자세한 내용은 [API 키](https://docs.didit.me/ko/console/api-keys.md)를 참조하세요.> [!TIP]
>
> `401` 에러가 발생하는 경우 올바른 애플리케이션에 대한 올바른 API 키를 사용하고 있는지, 그리고 키가 재생성되지 않았는지 다시 한번 확인하세요.


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