> ## 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 Authentication)

> Didit 인증 설정을 코드에서 직접 관리하세요. 소유자 승인 권한 또는 인증 범위 API 키로 로그인 방식, 설정, 브랜딩, 보호 기능을 활성화할 수 있습니다.

Didit Authentication을 사용하면 API로 로그인 방식을 활성화하고 애플리케이션 설정을 조회할 수 있습니다. 소유자가 승인한 권한 부여 또는 `authentication` 스코프가 지정된 명명된 API 키를 사용하세요.

> [!WARNING]
>
> Authentication은 새로운 기능입니다. 먼저 샌드박스 애플리케이션에서 방식을 설정한 다음, 라이브 애플리케이션에 설정하세요.

아래의 모든 호출은 애플리케이션의 Authentication 관리 API로 전송됩니다. `MANAGEMENT_BASE`는 다음과 같습니다.

```text theme={null}
https://apx.didit.me/auth/v2/organizations/{org_id}/applications/{application_id}/authentication/
```

같은 라우트는 `Setup` 태그 아래의 `openapi-authentication.json`에 설명되어 있으며, 서버 SDK는 이 파일을 바탕으로 다시 생성됩니다.

## 어떤 자격 증명을 사용할지

세 가지 자격 증명 중 어느 것이든 사용할 수 있으며, 각 자격 증명은 소유자가 승인한 범위로만 제한됩니다.

| 자격 증명 | 전송 방식 | 수행할 수 있는 작업 |
| - | - | - |
| `authentication` 범위가 있는 명명된 API 키 | `x-api-key: <key>` | 자신의 애플리케이션을 구성하고 읽습니다. `read` 권한이 있는 키는 설정을 읽기만 할 수 있으며, `write` 권한이 있는 키는 읽고 변경할 수 있습니다. |
| `didit:management`가 포함된, 소유자가 승인한 권한 부여 | `Authorization: Bearer <access_token>` | 동의 시 승인된 조직의 애플리케이션을 해당 사용자의 역할 범위 내에서 구성합니다. |
| 콘솔 세션 | `Authorization: Bearer <console session token>` | 사용자의 조직 멤버십과 역할에 따라 설정을 읽거나 변경합니다. 최종 사용자 보기에는 콘솔 세션과 적절한 권한도 필요합니다. |

다음 자격 증명은 요청 내용과 관계없이 모든 설정 경로에서 `403`으로 거부됩니다.

* 애플리케이션의 **기본 시크릿**.
* `POST /programmatic/login`에서 발급된 토큰. 이 토큰은 콘솔이 아니라 애플리케이션을 위해 발급됩니다.
* **`authentication` 범위가 없는** 키. 모든 리소스를 최상위 수준으로 설정해 만든 키도 포함됩니다. 이러한 키는 전체 액세스로 표시되고, `scopes`가 비어 있으며, 이 경로에서는 허용되지 않습니다.
* **다른 애플리케이션**의 키, `didit:verification`만 허용하는 권한 부여, 그리고 다른 조직을 위해 승인된 권한 부여.

자격 증명 없이 보낸 요청은 `401`로 응답합니다. 권한 부여와 키에는 그 자체의 제한도 추가로 적용됩니다. 권한 부여는 범위, 조직, 사용자의 역할에 따라 제한되고, 키는 범위, IP 허용 목록, 만료 시점에 따라 제한됩니다.

## 접근 승인

### 이름이 지정된 API 키 사용

[Business Console](https://business.didit.me)에서 **Developers -> API keys**를 열고, 설정하려는 애플리케이션용 키를 만드십시오. `authentication` 리소스에 **read** 또는 **write** 권한을 부여하십시오. read는 설정을 읽는 모든 호출(`GET`)을 허용합니다. write는 설정을 변경하는 모든 호출(`POST`, `PUT`, `PATCH`, `DELETE`)을 허용하며, 설정을 읽는 작업도 함께 허용합니다. 만료, IP 허용 목록, 교체에 관한 내용은 [API 키](https://docs.didit.me/ko/console/api-keys.md)를 참조하십시오. 키는 하나의 애플리케이션에 속하며, 그 애플리케이션에서만 작동합니다.

### MCP 연결을 통한 접근

Didit MCP 서버에 연결된 에이전트는 소유자가 동의 화면에서 승인한, `didit:management` 권한 범위가 포함된 권한 부여를 사용합니다. [MCP 인증](https://docs.didit.me/ko/integration/mcp/authentication.md#didit로-로그인)을 참조하십시오.

### 비밀번호가 없는 소유자

디바이스 코드 권한 부여([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628))를 사용하면 Google, 패스키 또는 이메일로 받은 코드로 로그인한 소유자가 비밀번호를 입력하지 않고도 어떤 브라우저에서든 같은 접근을 승인할 수 있습니다. [브라우저 없이 로그인](https://docs.didit.me/ko/integration/mcp/authentication.md#브라우저-없이-로그인-기기-코드)을 참조하십시오.

## 이메일 코드 활성화

`PUT methods/{name}/`는 `enabled`를 받으며, 자격 증명이 필요 없는 방식에는 이 값만 전달합니다.

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/code/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```

응답으로 현재 상태의 해당 방식이 반환됩니다:

```json theme={null}
{"name": "code", "enabled": true}
```

설정을 다시 읽으면 이메일 코드 항목에 `credential_source: null`이 포함됩니다. 항상 활성 상태인 방식은 비활성화할 수 없으며, 그 요청에는 `{"enabled": "always_on"}`이 응답으로 반환됩니다.

## Enable Google

소셜 방식은 고객사의 OAuth 앱 자격 증명을 사용하거나, 샌드박스 애플리케이션에서는 Didit의 테스트 앱을 사용할 수 있습니다.

### 고객사 Google 앱 사용

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/google/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "credentials": {"client_id": "1234.apps.googleusercontent.com", "client_secret": "GOCSPX-..."}}'
```

응답으로 반환되는 `callback_uri`를 사용 중인 제공자에 등록하십시오. 시크릿은 쓰기 전용입니다. 어떤 응답에서도 반환되지 않으며, 읽을 수 있는 값은 `client_id`뿐입니다. 이전에 저장된 자격 증명이 없는 상태에서 자격 증명 없이 방식을 켜면 `{"credentials": "required"}`가 응답됩니다.

### Didit 테스트 앱 사용 (`didit_test`)

**샌드박스 애플리케이션**은 고객사의 앱 대신 Didit의 소셜 앱을 사용할 수 있습니다. 설정을 완료하고 정상 동작을 확인하기에는 이것으로 충분합니다.

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/google/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "credential_source": "didit_test"}'
```

`didit_test`는 샌드박스 애플리케이션에서만 **Google, Microsoft, Apple, GitHub**를 지원합니다.

| 응답 | 조건 |
| - | - |
| `{"credential_source": "sandbox_only"}` | 애플리케이션이 라이브 상태입니다. 테스트 앱은 라이브 로그인을 제공하지 않습니다. |
| `{"credential_source": "unavailable"}` | 배포 환경에 해당 제공자용 테스트 앱이 없으므로 방식이 꺼진 상태로 유지됩니다. |
| `configured: true`가 포함된 `200` | 테스트 앱이 해당 방식을 제공하며, 호스팅 로그인에 이 방식이 표시됩니다. |

설정에 대한 `GET` 요청은 이 애플리케이션에서 테스트 앱이 제공할 수 있는 제공자를 `didit_test_credentials`에 나타냅니다. 라이브 애플리케이션에서는 네 제공자 모두 `false`입니다.

## 설정 재조회

`MANAGEMENT_BASE`에 `GET` 요청을 보내면 설정을 다시 확인할 수 있습니다. 응답에는 각 방식의 `enabled`와 `credential_source`, 콜백 URL, 세션 규칙, 가입 정책이 모두 포함됩니다.

```bash theme={null}
curl --fail-with-body "$MANAGEMENT_BASE" -H "x-api-key: $DIDIT_API_KEY"
```

```json theme={null}
{
  "enabled": true,
  "methods": [
    {"name": "code", "enabled": true, "credential_source": null},
    {"name": "google", "enabled": true, "credential_source": "didit_test", "configured": true, "client_id": "didit-test-google"},
    {"name": "password", "enabled": false, "credential_source": null}
  ],
  "didit_test_credentials": {"google": true, "microsoft": true, "apple": true, "github": true},
  "redirect_uris": ["https://app.example.com/auth/callback"]
}
```

비활성화된 방식도 목록에 포함되므로, `GET` 요청 한 번으로 어떤 방식이 켜져 있고 어떤 방식이 꺼져 있는지 확인할 수 있습니다. 응답 최상단의 `enabled`는 해당 애플리케이션에서 인증이 비활성화된 경우 `false`입니다. 관리 권한이나 이름이 지정된 키로 설정을 변경하면 `409`와 `{"detail": "product_disabled"}`가 반환되며, 아무것도 저장되지 않습니다. 설정 호출로는 인증을 켤 수 없습니다. 인증을 켜는 것은 콘솔에서 사용자가 애플리케이션별로 직접 수행하며, 그 이후부터 API 호출이 동작합니다.

## The rest of the setup

| Route, under `MANAGEMENT_BASE` | Methods | What it holds |
| - | - | - |
| `settings/` | `GET`, `PATCH` | 에이전트 접근, 조직, MFA 정책, 기본 멤버 역할, 비활성화된 webhook 이벤트 |
| `onboarding/` | `GET`, `PATCH` | 완료된 설정 단계, 그리고 사용자가 호스팅 로그인 페이지에서 로그인할지 자체 화면에서 로그인할지 여부 |
| `branding/` | `GET`, `PATCH` | 호스팅 페이지의 텍스트와 법적 링크(로고와 색상은 커스터마이징에서 설정) |
| `protection/` | `GET`, `PATCH` | 봇 보호 정책([봇 보호](https://docs.didit.me/ko/authentication/bot-protection.md)) |
| `verified/` | `GET`, `PATCH` | 가입 시 인증 수준, 단계 상향 규칙, 토큰 클레임 |
| `emails/`, `emails/{key}/` | `GET` | 이 애플리케이션이 보내는 로그인 이메일과 렌더링된 미리보기 |
| `domain/` | `GET`, `PUT`, `DELETE` | 호스팅 오리진과 사용자 지정 로그인 도메인 |
| `domain/verify/`, `domain/activate/` | `POST` | 도메인의 DNS와 인증서를 확인한 뒤 기준 오리진으로 설정 |
| `native-apps/` | `GET`, `PUT` | 애플리케이션의 패스키를 공유하는 iOS 및 Android 앱 |

권한 부여(grant) 또는 키로는 설정과 그 카운터만 접근할 수 있으며, 최종 사용자 데이터에는 접근할 수 없습니다. `users/`, `sessions/`, `sign-ins/`, `overview/`, 고객 조직, 역할, 가져오기, 에이전트 세션, 테스트 이메일은 여전히 콘솔 세션이 필요합니다.

`agent_humans_only` 설정은 애플리케이션 전체에 적용됩니다. 이 설정은 조직 소유자 또는 관리자만 변경할 수 있습니다. 이름이 지정된 키로 요청하면 `403 owner_or_admin_required`가 반환됩니다. 이 설정을 켜려면 등록된 패스키도 필요합니다(`passkey_required`).

## Errors

| 응답 | 의미 |
| - | - |
| `401` | 자격 증명이 없습니다. |
| `403` | 이 애플리케이션을 설정할 수 없는 자격 증명 또는 자격 증명 자체의 제한 때문입니다: `ip_not_allowed`, 만료된 API 키, 쓰기 경로에 사용한 읽기 전용 키. |
| `409 {"detail": "product_disabled"}` | 애플리케이션에 대해 인증이 꺼져 있어, 권한 부여나 키로 수행한 설정 변경이 거부됩니다. 사용자가 콘솔에서 인증을 켭니다. |
| `400 {"<field>": "<code>"}` | `sandbox_only`, `unavailable`, `not_supported`, `required`, `always_on`, `method_unavailable`, `unknown_field`. |
| `404` | 요청한 리소스를 찾을 수 없습니다. |


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