---
title: "동의 화면 주소 발급 (OAuth 연동 시작)"
method: POST
path: "/v1/credentials/consent-url"
tags: ["CredentialLink"]
---

# 동의 화면 주소 발급 (OAuth 연동 시작)

`POST /v1/credentials/consent-url`

## Request

- Base URL: `https://api.xdata.kr` (the document declares no server; this is the origin it was published from)
- URL: `https://api.xdata.kr/v1/credentials/consent-url`
- Auth: one of:
  - HTTP basic
  - OAuth 2 (authorization code, authorization URL `https://api.xdata.kr/oauth/authorize`, token URL `https://api.xdata.kr/oauth/token`)

`POST /v1/credentials/consent-url` — 고객을 보낼 동의 화면 주소를 만든다 (E3).

폼으로 연결하는 provider(인증서 · 아이디/비밀번호)와 달리, 동의 왕복 provider 는 고객이
플랫폼 화면에서 허락한 뒤 돌아온다. 이 엔드포인트가 그 **시작점**이고, 돌아온 뒤에는
지금까지와 같은 단일 진입점 `POST /v1/credentials/link` 로 인가 코드를 보낸다.

주소 안의 값은 전부 서버가 정한다 — 범위 · 동의 주소는 상품 어댑터가, 복귀 주소는
`public_urls` 한 곳이, `state` 는 서명이 만든다. 화면이 보낸 값을 그대로 쓰지 않는다.

## Query parameters

- `env_scope` 'production' | 'real_test' | 'sandbox', nullable: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.

## Headers

- `Authorization` string, nullable
- `X-Env-Scope` 'production' | 'real_test' | 'sandbox', nullable: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.

## Request body

- CredentialConsentUrlRequest: `POST /v1/credentials/consent-url` 요청 본문. **provider 하나만** 받는다. 복귀 주소를 화면에서 받지 않는 이유: 그 값을 그대로 쓰면 열린 리디렉션이 되고, 플랫폼에 등록한 주소와 글자 그대로 같아야 해서 화면이 정할 수 있는 값이 아니다. 서버가 `public_urls` 한 곳에서 만든다.
  - `provider` string, required: 연동할 기관(provider) id
  - `features` string[], nullable: Optional feature bundles to request consent for. Omit to request the provider's default scope set. Unknown names are rejected with 400.

## Response `200`

Consent URL issued

- unknown

## Other responses

- `400`: Provider does not use a consent redirect
- `422`: Validation Error

---

[API](https://skmtc.dev/xdata/apis/xboss-api.md) · [All operations](https://skmtc.dev/xdata/apis/xboss-api/llms.txt) · [OpenAPI document](https://skmtc.dev/xdata/apis/xboss-api/revisions/816de78950db?raw)