API 레퍼런스
세션 발급
기관이 인증한 고객의 단기 세션을 생성합니다.
POST /v1/sessions
기관 백엔드에서 호출합니다. 헤더에 x-wss-institution-key와 Content-Type: application/json을 전달합니다. 인증 규칙을 함께 확인하세요.
요청 예제
curl "$WSS_BFF_URL/v1/sessions" \
--request POST \
--header "x-wss-institution-key: $WSS_INSTITUTION_KEY" \
--header "Content-Type: application/json" \
--data '{
"tenantId": "YOUR_TENANT_ID",
"customerRef": "customer-123",
"requestedKeyAdapter": "took-sar"
}'요청 본문
| 필드 | 타입 | 필수 | 제약과 의미 |
|---|---|---|---|
| tenantId | string | 필수 | 등록된 기관 식별자. null·기본값 없음. |
| customerRef | string | 필수 | 기관이 인증한 고객 참조. 3~128자, null·기본값 없음. |
| requestedKeyAdapter | string | 선택 | took-sar, thirdweb-user-wallet, fsl-mpc. 생략 시 기관 manifest의 기본 어댑터를 사용합니다. null은 사용하지 않습니다. |
기관이 허용한 키 어댑터만 선택할 수 있습니다. 공급자의 운영 연동 여부는 별도로 확인해야 합니다.
성공 응답
HTTP 201 Created. 아래 토큰·시각·주소는 형식 설명을 위한 예시입니다.
{
"sessionToken": "<signed-session-jwt>",
"expiresAt": "2026-10-23T06:15:00.000Z",
"walletUrl": "https://wallet.example.com"
}| 필드 | 타입 | 필수·null | 의미 |
|---|---|---|---|
| sessionToken | string | 필수, null 불가 | HS256 JWT 형식의 단기 세션 토큰. 고객 앱에 전달합니다. |
| expiresAt | string | 필수, null 불가 | ISO 형식의 만료 시각. |
| walletUrl | string | 필수, null 불가 | 해당 환경의 지갑 URL. 호스트 iframe에 연결합니다. |
오류 응답
{ "error": "institution_auth_required" }| HTTP | error | 대응 |
|---|---|---|
| 401 | institution_auth_required | 기관 키가 누락되거나 일치하지 않습니다. 서버 설정을 확인합니다. |
| 404 | tenant_not_found | 등록된 기관 식별자를 사용합니다. |
| 400 | key_adapter_not_allowed | 해당 기관의 허용 어댑터를 확인합니다. |
| 400 | request_rejected | 요청 필드·타입·길이를 확인합니다. |
| 403 | origin_not_allowed | 승인된 호출 출처를 사용합니다. |
error는 필수 string이며 null·기본값이 없습니다. 공통 오류 분류는 오류 처리를 확인하세요.
재시도와 중복 요청
멱등성 키·재시도 간격은 미확정입니다. 같은 요청이 같은 세션을 반환한다고 가정하지 마세요. 고객 문맥과 만료 여부를 확인한 후 새 세션을 발급합니다.