> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bonanzalab.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 토큰 발급 및 이용 안내

> Access Token 발급 절차와 API·WebSocket 인증 방법, 토큰 만료 처리 및 보안 수칙을 안내합니다.

Dayfin API와 WebSocket은 **Access Token**으로 요청을 인증합니다.

Client ID와 Client Secret은 토큰을 발급받기 위한 고객사 고유의 인증 정보이고, Access Token은 실제로 API를 호출하거나 WebSocket에 연결할 때 사용합니다.

> [!WARNING]
>
> Client Secret과 Access Token은 고객사 인증 정보입니다. 외부에 노출되지 않도록 안전하게 관리해 주세요.

## 이용 절차

**1. 인증 정보 수령**

Client ID, Client Secret, Scope를 전달받습니다.

**2. Access Token 발급**

Client ID와 Client Secret으로 토큰 발급 API를 호출해 Access Token을 받습니다.

**3. API·WebSocket 이용**

발급받은 Access Token으로 API를 호출하거나 WebSocket에 연결합니다.

**4. 만료 전 재발급**

토큰이 만료되기 전에 토큰 발급 API를 다시 호출해 새 토큰으로 교체합니다.

## Access Token 발급

```text theme={null}
POST https://api.dayfin.io/oauth/token
```

Client ID와 Client Secret은 HTTP Basic 인증 방식으로 전달합니다. 두 값을 콜론(`:`)으로 연결해 Base64로 인코딩한 값을 `Authorization` 헤더에 넣습니다.

```text theme={null}
Authorization: Basic Base64({CLIENT_ID}:{CLIENT_SECRET})
```

### 요청 헤더

| 헤더 | 필수 | 설명 |
| - | :-: | - |
| `Authorization` | Y | `Basic Base64(Client ID:Client Secret)` |
| `Content-Type` | Y | `application/x-www-form-urlencoded` 권장 (`application/json`도 지원) |
| `Accept` | N | `application/json` |

### 요청 파라미터

요청 본문에는 발급 방식과 Scope를 담습니다. `Content-Type`에 따라 Form 또는 JSON 형식으로 전달할 수 있습니다.

| 이름 | 타입 | 필수 | 설명 |
| - | - | :-: | - |
| `grant_type` | String | Y | `client_credentials` 고정 |
| `scope` | String | Y | 계약 시 할당받은 Scope |

### 요청 예제

```bash Form theme={null}
curl --request POST \
  --url "https://api.dayfin.io/oauth/token" \
  --user "{CLIENT_ID}:{CLIENT_SECRET}" \
  --header "Accept: application/json" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "scope={ASSIGNED_SCOPE}"
```

```bash JSON theme={null}
curl --request POST \
  --url "https://api.dayfin.io/oauth/token" \
  --user "{CLIENT_ID}:{CLIENT_SECRET}" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "grant_type": "client_credentials",
    "scope": "{ASSIGNED_SCOPE}"
  }'
```

### 응답 예제

발급에 성공하면 `rspCode`가 `A0000`인 응답과 함께 Access Token이 반환됩니다. 이후 요청에는 `access_token` 값을 사용합니다.

```json theme={null}
{
  "rspCode": "A0000",
  "rspMessage": "정상",
  "access_token": "{ACCESS_TOKEN}",
  "token_type": "bearer",
  "expires_in": 3599,
  "scope": "{ASSIGNED_SCOPE}",
  "jti": "550e8400-e29b-41d4-a716-446655440000"
}
```

### 응답 필드

| 이름 | 타입 | 설명 |
| - | - | - |
| `rspCode` | String | 처리 결과 코드. 성공 시 `A0000` |
| `rspMessage` | String | 처리 결과 메시지 |
| `access_token` | String | API 호출에 사용할 Access Token (JWT) |
| `token_type` | String | 토큰 타입. `bearer` |
| `expires_in` | Number | 토큰의 남은 유효시간(초) |
| `scope` | String | 요청한 Scope |
| `jti` | String | 발급된 토큰의 고유 식별자 |

> [!NOTE]
>
> `expires_in`은 고객사별 설정에 따라 달라질 수 있습니다. 응답값을 기준으로 만료 시점을 계산해 주세요.

## API 요청 인증

API를 호출할 때는 발급받은 Access Token을 `Authorization` 헤더에 `Bearer` 형식으로 담아 전달합니다. 모든 API 요청에 동일하게 적용됩니다.

```text theme={null}
Authorization: Bearer {ACCESS_TOKEN}
```

```bash theme={null}
curl --request GET \
  --url "https://api.dayfin.io/v2/api/{API_PATH}" \
  --header "Authorization: Bearer {ACCESS_TOKEN}" \
  --header "Accept: application/json"
```

> [!WARNING]
>
> * `Bearer`는 대소문자를 구분하므로 정확히 입력해 주세요.
> * `Bearer`와 토큰 사이에는 공백 한 칸이 필요합니다.
> * Query String으로 토큰을 전달하는 방식은 지원하지 않습니다.

WebSocket도 동일한 Access Token을 사용합니다. 연결 방법은 [WebSocket 이용 안내](https://docs.bonanzalab.io/TODO-WS안내-경로)를 참고해 주세요.

## 토큰 만료 및 재발급

Access Token은 보안을 위해 유효기간이 정해져 있으며, 만료된 토큰으로 요청하면 인증 오류가 발생합니다. 토큰이 만료되었거나 만료가 임박하면 토큰 발급 API(`/oauth/token`)를 다시 호출해 새 토큰을 받아 주세요.

안정적인 연동을 위해 다음과 같이 처리하는 것을 권장합니다.

1. 토큰 발급 시 `expires_in`을 기준으로 만료 시점을 저장합니다.
2. 실제 만료 시점보다 여유를 두고 새 토큰을 발급받습니다.
3. API 호출 중 토큰 만료 오류가 발생하면 새 토큰을 발급받아 재시도합니다.

> [!TIP]
>
> 매 요청마다 토큰을 새로 발급받지 말고, 유효한 토큰을 재사용해 주세요.

## 오류 응답

오류 발생 시 HTTP 상태 코드와 함께 `rspCode`, `rspMessage`가 반환됩니다.

```json theme={null}
{
  "rspCode": "A7773",
  "rspMessage": "등록된 기관정보가 없습니다."
}
```

### 토큰 발급 오류

| HTTP 상태 | rspCode | 발생 조건 |
| :-: | - | - |
| 401 | `A7771` | `grant_type` 누락 |
| 401 | `A7772` | `scope` 누락 |
| 401 | `A7773` | Client ID 또는 Client Secret 불일치 |
| 401 | `A7774` | 허용되지 않은 Scope |
| 401 | `A7775` | 허용되지 않은 Grant Type |
| 401 | `A1015` | 등록되지 않은 IP에서 요청 |
| 500 | `A7779` | 토큰 생성 실패 |
| 500 | `A1002` | 요청 처리 중 서버 오류 |

### API 인증 오류

| HTTP 상태 | rspCode | 발생 조건 |
| :-: | - | - |
| 403 | `A1004` | 토큰 유효기간 만료 |

토큰 만료 외에도 다음과 같은 경우 인증 오류가 발생할 수 있습니다.

* `Authorization` 헤더 누락 또는 `Bearer` 형식 오류
* 변조되었거나 서명이 유효하지 않은 토큰

인증에 성공하더라도 허용 IP, API 이용 권한, [호출 한도](https://docs.bonanzalab.io/rate-limits.md)에 따라 요청이 거부될 수 있습니다.


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