---
title: 인증
description: Human Dashboard로 인증하고, 조직을 설정하고, 모든 Human Token API 요청에 사용하는 x-unico-accesskey를 생성하는 방법.
canonical: https://developer.unico.io/ko/human-token/get-started/authentication
locale: ko
generated_by: markdown-export
---

- [/ko/](/ko/)
- 시작하기
- 인증

**이 페이지에서# 인증

이 가이드는 Human Dashboard로 인증하고 모든 Human Token API 요청에 사용할 `x-unico-accesskey`를 생성하는 과정을 안내합니다.
이 흐름은 두 페이즈로 구성됩니다:

**인증** — 로그인을 완료하고 액세스 토큰을 받습니다. 두 가지 인증 방법을 사용할 수 있습니다:

**생체 인식 로그인** — Unico SDK를 통한 얼굴 캡처(가입과 로그인 모두 지원)
**이메일 OTP 로그인** — 등록된 이메일 주소로 전송되는 일회용 코드(로그인 전용)

**조직 설정** — 회사 프로필을 생성하고 액세스 키를 생성합니다(최초 가입 시에만)

### 자격 증명을 설정하는 두 가지 방법​

이 가이드의 모든 작업은 [dashboard.unico.app](https://dashboard.unico.app)의 **Human Dashboard**에서도 수행할 수 있습니다. API 호출은 필요하지 않습니다.
옵션사용 시점**대시보드**초기 설정, 수동 키 로테이션, 가끔 하는 관리**API**자동 프로비저닝, CI/CD 파이프라인, 프로그래밍 방식의 키 관리
#### 대시보드 사용​

[dashboard.unico.app](https://dashboard.unico.app)으로 이동합니다.
**가입 또는 로그인** — 생체 인식 로그인(얼굴 캡처) 또는 이메일 OTP를 사용합니다.
**조직 생성** — 회사 이름, 국가, 허용 도메인을 입력합니다.
**액세스 키 생성** — **Access Keys**로 이동하여 **Create key**를 클릭합니다. 키는 한 번만 표시되므로 즉시 복사하세요.
**브랜치 관리** — **Branches**에서 브랜치를 생성하고 구성합니다. 각 브랜치는 자체 액세스 키를 생성합니다.

대시보드에서 받은 액세스 키는 모든 API 요청에서 사용하는 `x-unico-accesskey`와 동일합니다. 두 방법은 완전히 호환됩니다.
### 기본 URL​

이 페이지의 모든 엔드포인트는 Human Dashboard API에서 제공됩니다. Create Process 및 Get Process와 같은 Human Token API 요청은 [환경](/ko/human-token/get-started/environments)에 나열된 API 호스트로 전송됩니다.
환경API기본 URL프로덕션Human Dashboard API(로그인, 조직, 액세스 키 및 브랜치)`https://api.humantoken.unico.app`
### 인증 방법​

인증하고 `authToken`을 받는 데 두 가지 방법을 사용할 수 있습니다:
방법엔드포인트사용 시점**생체 인식**`POST /api/console/v1/auth/biometric/sessions`가입(신규 계정) 또는 로그인(기존 사용자)**이메일 OTP**`POST /api/console/v1/auth/email/sessions`로그인 전용 — 계정이 이미 존재해야 함
### 생체 인식 로그인 intent​

`POST /api/console/v1/auth/biometric/sessions`를 호출할 때마다 `intent`를 선언해야 합니다:
`intent`사용 시점`email` 필드`name` 필드`LOGIN_INTENT_SIGNUP`최초 등록 — 신규 계정 생성**필수****필수**`LOGIN_INTENT_SIGNIN`기존 사용자 — 계정이 이미 존재함사용 안 함사용 안 함(생략)`LOGIN_INTENT_SIGNIN`으로 처리됨사용 안 함사용 안 함
intent는 세션을 폴링할 때(2단계) 수행되는 검증을 제어합니다:

**SIGNUP** — 해당 생체 인식 신원이 이미 등록되어 있으면 로그인을 거부합니다(중복 계정 방지).
**SIGNIN** — 해당 생체 인식 신원이 등록되어 있지 않으면 로그인을 거부합니다(로그인하려면 계정이 존재해야 함).

### 페이즈 1 — 인증​

#### 1단계: 생체 인식 로그인 세션 시작​

**SIGNUP(최초 등록)**
```
curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions \  -H "Content-Type: application/json" \  -d '{    "intent": "LOGIN_INTENT_SIGNUP",    "email": "admin@acme.com",    "name": "Jane Doe"  }'
```

이메일 고유성해당 이메일로 이미 등록된 계정이 있으면 요청은 `400 Bad Request`를 반환합니다.
응답:
```
{  "session": {    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",    "link": "",    "token": ""  }}
```

SIGNUP의 경우 응답의 `link` 및 `token` 필드는 비어 있으며, 생체 인식 캡처 링크는 제공된 이메일 주소로 전송됩니다.
**SIGNIN(기존 사용자)**
```
curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions \  -H "Content-Type: application/json" \  -d '{    "intent": "LOGIN_INTENT_SIGNIN"  }'
```

응답:
```
{  "session": {    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",    "link": "https://humantoken.unico.io/...",    "token": "eyJhbGciOiJSUzI1NiJ9..."  }}
```

`sessionId`를 저장하세요.

**SIGNUP**: 생체 인식 캡처 링크가 1단계에서 제공한 이메일로 전송됩니다. 사용자에게 받은편지함을 확인하고 캡처를 완료하도록 안내하세요.
**SIGNIN**: 브라우저에서 `link`를 열고 생체 인식 캡처를 완료합니다.

#### 2단계: 세션이 확정될 때까지 폴링​

```
curl https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions/b3f1a2c4-0000-0000-0000-abcdef012345
```

`status`가 최종 상태에 도달할 때까지 2~3초마다 폴링하세요.
`status``outcome`의미`pending``pending`사용자가 아직 캡처를 완료하지 않음 — 계속 폴링`processing``pending`캡처 완료, 결과 계산 중 — 계속 폴링`completed``matched`로그인 성공 — `authToken`이 포함됨`completed``no_match`생체 인식이 어떤 기록과도 일치하지 않음`completed``inconclusive`캡처는 성공했지만 확정할 수 없음`expired`—링크 만료 — 1단계부터 다시 시작`canceled`—세션이 취소됨 — 1단계부터 다시 시작
**세션 폴링 시 발생하는 intent별 추가 오류:**
HTTP조건`400`**SIGNUP** — 생체 인식 신원이 이미 등록됨(중복 계정)`400`**SIGNIN** — 생체 인식 신원이 등록되지 않음(계정이 존재하지 않음)
성공 응답:
```
{  "result": {    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",    "status": "completed",    "outcome": "matched",    "authToken": "eyJhbGciOiJSUzI1NiJ9..."  }}
```

`authToken`을 저장하세요. 이후의 모든 Human Dashboard API 요청에서 `x-console-authorization` 헤더로 사용합니다.
### 페이즈 1(대안) — 이메일 OTP 로그인​

사용자에게 이미 계정이 있고 등록된 이메일로 전송되는 일회용 코드로 인증하기를 원하는 경우, 생체 인식 대신 이 흐름을 사용하세요. **이메일 OTP로는 가입할 수 없습니다** — 최초 등록에는 생체 인식 흐름을 사용하세요.
#### 1단계: OTP 전송​

```
curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/email/sessions \  -H "Content-Type: application/json" \  -d '{    "email": "admin@acme.com"  }'
```

참고이메일은 기존 계정에 속해야 합니다. 계정을 찾을 수 없으면 2단계(OTP 검증)에서 `404 Not Found`를 반환합니다.
응답:
```
{  "session": {    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345"  }}
```

`sessionId`를 저장하세요. 제공된 이메일 주소로 6자리 코드가 전송됩니다.
#### 2단계: OTP 검증​

```
curl https://api.humantoken.unico.app/api/console/v1/auth/email/sessions/{sessionId}/{code}
```

HTTP조건`200`코드가 유효함 — `authToken`이 포함됨`400`코드가 잘못됨(`invalid otp code`)`400`OTP가 이미 사용되었거나, 최대 시도 횟수에 도달했거나, 만료됨`404`등록되지 않은 이메일
성공 응답:
```
{  "result": {    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",    "status": "completed",    "outcome": "matched",    "authToken": "eyJhbGciOiJSUzI1NiJ9..."  }}
```

`authToken`을 저장하세요. 이후의 모든 Human Dashboard API 요청에서 `x-console-authorization` 헤더로 사용합니다.
### 페이즈 2 — 조직 설정​

#### 3단계: 조직 생성​

참고이 호출은 **한 번만** 할 수 있습니다. 테넌트를 프로비저닝하고 `branchId`를 생성합니다.
모든 국가가 허용됩니다. [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) 세 글자 코드를 사용하세요(예: `BRA`, `USA`, `MEX`, `DEU`, `IND`). `taxId`는 모든 국가에서 선택 사항입니다.
```
curl -X POST https://api.humantoken.unico.app/api/console/v1/organization \  -H "x-console-authorization: <authToken>" \  -H "Content-Type: application/json" \  -d '{    "name": "Acme Corp",    "responsibleEmail": "admin@acme.com",    "websiteUrl": "https://acme.com",    "countryCode": "BRA",    "logo": "https://acme.com/logo.png",    "allowedDomains": ["https://app.acme.com"]  }'
```

응답:
```
{  "organization": {    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",    "name": "Acme Corp",    "responsibleEmail": "admin@acme.com",    "websiteUrl": "https://acme.com",    "countryCode": "BRA",    "tenantId": "tenant-acme-prod",    "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",    "taxId": "12345678000195"  }}
```

`branchId`를 저장하세요. 기본 브랜치를 식별하며, 브랜치와 액세스 키를 관리할 때 사용됩니다.
#### 4단계: 액세스 키 생성​

```
curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys \  -H "x-console-authorization: <authToken>" \  -H "Content-Type: application/json" \  -d '{    "label": "production-key"  }'
```

응답:
```
{  "accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"}
```

경고**`accessKey`는 한 번만 반환되며 다시 조회할 수 없습니다.** 즉시 시크릿 매니저에 `HUMAN_TOKEN_ACCESS_KEY`로 저장하세요.
이 값이 모든 Human Token API 요청에서 사용하는 `x-unico-accesskey` 헤더입니다.
### 이제 갖게 된 것​

값사용 위치`branchId`기본 브랜치 식별, 브랜치별 액세스 키 생성`accessKey`모든 Human Token 요청의 `x-unico-accesskey` 헤더
### 조직 관리​

#### 조직 조회​

```
curl https://api.humantoken.unico.app/api/console/v1/organization/<organizationId> \  -H "x-console-authorization: <authToken>"
```

응답:
```
{  "organization": {    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",    "name": "Acme Corp",    "responsibleEmail": "admin@acme.com",    "websiteUrl": "https://acme.com",    "countryCode": "BRA",    "tenantId": "tenant-acme-prod",    "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",    "taxId": "12345678000195"  }}
```

#### 조직 업데이트​

```
curl -X PUT https://api.humantoken.unico.app/api/console/v1/organization \  -H "x-console-authorization: <authToken>" \  -H "Content-Type: application/json" \  -d '{    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",    "name": "Acme Corp",    "responsibleEmail": "admin@acme.com",    "websiteUrl": "https://acme.com",    "countryCode": "BRA",    "taxId": "12345678000195",    "logo": "https://acme.com/logo-updated.png",    "allowedDomains": ["https://app.acme.com", "https://checkout.acme.com"]  }'
```

### 액세스 키 관리​

**키 목록 조회**(메타데이터만 — 시크릿은 반환되지 않음):
```
curl https://api.humantoken.unico.app/api/console/v1/access-keys \  -H "x-console-authorization: <authToken>"
```

**키 로테이션**(기존 키는 즉시 무효화됨):
```
curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys/rotate \  -H "x-console-authorization: <authToken>" \  -H "Content-Type: application/json" \  -d '{"accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"}'
```

**키 폐기**(되돌릴 수 없음):
```
curl -X DELETE https://api.humantoken.unico.app/api/console/v1/access-keys \  -H "x-console-authorization: <authToken>" \  -H "Content-Type: application/json" \  -d '{"accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"}'
```

### 브랜치 관리​

브랜치를 사용하면 제품 또는 환경별로 조직 구성(이름, 로고, 허용 도메인)을 분리할 수 있습니다. 각 브랜치에는 자체 액세스 키가 있으므로, 브랜치 컨텍스트는 요청에 사용된 키에서 자동으로 확인됩니다. `CreateProcess`에 `branchId`를 전달할 필요가 없습니다.
#### 브랜치 생성​

```
curl -X POST https://api.humantoken.unico.app/api/console/v1/organization/branches \  -H "x-console-authorization: <authToken>" \  -H "Content-Type: application/json" \  -d '{    "name": "Mobile App",    "logo": "https://acme.com/mobile-logo.png",    "allowedDomains": ["https://mobile.acme.com"]  }'
```

응답:
```
{  "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345"}
```

`branchId`를 저장하세요. 브랜치별 액세스 키를 생성할 때 사용합니다.
#### 브랜치 업데이트​

```
curl -X PUT https://api.humantoken.unico.app/api/console/v1/organization/branches \  -H "x-console-authorization: <authToken>" \  -H "Content-Type: application/json" \  -d '{    "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345",    "name": "Mobile App v2",    "logo": "https://acme.com/mobile-logo-v2.png",    "allowedDomains": ["https://mobile.acme.com", "https://app.acme.com"]  }'
```

#### 브랜치별 액세스 키 생성​

특정 브랜치로 범위가 지정된 액세스 키를 생성하려면 요청 본문에 `branchId`를 포함하세요:
```
curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys \  -H "x-console-authorization: <authToken>" \  -H "Content-Type: application/json" \  -d '{    "label": "mobile-app-key",    "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345"  }'
```

응답:
```
{  "accessKey": "uip_ak.prod.z9y8x7w6.v5u4t3s2.r1q0p9o8"}
```

경고**`accessKey`는 한 번만 반환됩니다.** 즉시 저장하세요. 이 키로 인증된 모든 `CreateProcess` 요청은 해당 키에 연결된 브랜치 구성을 자동으로 사용합니다.마지막 업데이트 2026년 10월 21일**에