인증

이 가이드는 Human Dashboard로 인증하고 모든 Human Token API 요청에 사용할 x-unico-accesskey를 생성하는 과정을 안내합니다.

이 흐름은 두 페이즈로 구성됩니다:

인증 — 로그인을 완료하고 액세스 토큰을 받습니다. 두 가지 인증 방법을 사용할 수 있습니다:
- 생체 인식 로그인 — Unico SDK를 통한 얼굴 캡처(가입과 로그인 모두 지원)
- 이메일 OTP 로그인 — 등록된 이메일 주소로 전송되는 일회용 코드(로그인 전용)
조직 설정 — 회사 프로필을 생성하고 액세스 키를 생성합니다(최초 가입 시에만)

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

이 가이드의 모든 작업은 dashboard.unico.app의 Human Dashboard에서도 수행할 수 있습니다. API 호출은 필요하지 않습니다.

옵션	사용 시점
대시보드	초기 설정, 수동 키 로테이션, 가끔 하는 관리
API	자동 프로비저닝, CI/CD 파이프라인, 프로그래밍 방식의 키 관리

대시보드 사용

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

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

기본 URL

이 페이지의 모든 엔드포인트는 Human Dashboard API에서 제공됩니다. Create Process 및 Get Process와 같은 Human Token API 요청은 환경에 나열된 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": "[email protected]",
    "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": "[email protected]"
  }'

참고

이메일은 기존 계정에 속해야 합니다. 계정을 찾을 수 없으면 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 세 글자 코드를 사용하세요(예: 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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
    "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 요청은 해당 키에 연결된 브랜치 구성을 자동으로 사용합니다.

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

대시보드 사용​

기본 URL​

인증 방법​

생체 인식 로그인 intent​

페이즈 1 — 인증​

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

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

페이즈 1(대안) — 이메일 OTP 로그인​

1단계: OTP 전송​

2단계: OTP 검증​

페이즈 2 — 조직 설정​

3단계: 조직 생성​

4단계: 액세스 키 생성​

이제 갖게 된 것​

조직 관리​

조직 조회​

조직 업데이트​

액세스 키 관리​

브랜치 관리​

브랜치 생성​

브랜치 업데이트​

브랜치별 액세스 키 생성​