> Agent-readable docs index: /llms.txt. Fetch only the needed Markdown pages first; use /docs.zip only for broad search after checking /docs-manifest.json or /docs.zip.sha256.

# 인증

## 인증 방법

인증 관련을 제외한 모든 API 요청은 인증 토큰(Auth Token)을 필요로 합니다.

인증 토큰은 HTTP Header에 포함되어야 합니다.

```http request
Authorization: {{Auth Token}}
```

_\* `Bearer` 와 같은 접두사는 필요하지 않습니다._

<details>
<summary>주요 개념</summary>
<dl>
<dt>API Key</dt>
<dd><strong>정의:</strong> KOS 팀이 병원에 발급하는 서버용 인증 키입니다.<br /><strong>설명:</strong> 인증 토큰을 발급받기 위한 입력값이며, 클라이언트에 노출하지 않고 서버 사이드에서만 사용해야 합니다.</dd>
<dt>인증 토큰(Auth Token)</dt>
<dd><strong>정의:</strong> API 요청 시 <code>Authorization</code> 헤더에 담아 전송하는 토큰입니다.<br /><strong>설명:</strong> 인증 관련 API를 제외한 모든 요청에 필요합니다. 일정 시간이 지나면 만료될 수 있으며, 만료된 토큰으로 호출하면 <code>401</code> 응답이 반환됩니다.</dd>
<dt>인증 토큰 교환</dt>
<dd><strong>정의:</strong> API Key를 인증 토큰으로 바꾸는 서버 사이드 절차입니다.<br /><strong>설명:</strong> 클라이언트에서 수행하면 API Key가 노출될 수 있으므로 반드시 서버에서만 호출해야 합니다.</dd>
<dt>Authorization 헤더</dt>
<dd><strong>정의:</strong> 인증 토큰을 전달하는 HTTP 헤더입니다.<br /><strong>설명:</strong> 값에는 인증 토큰만 넣으며, <code>Bearer</code> 같은 접두사는 붙이지 않습니다.</dd>
</dl>
</details>

<Callout type="danger">
<p><strong>절대로 API Key와 인증 토큰을 클라이언트 노출하지 마세요.</strong></p>
<p>클라이언트에 노출되거나, 클라이언트에서 저장되지 않도록 주의해야 합니다.</p>
<p>인증 토큰 교환 또한 절대로 클라이언트에서 이루어지면 안됩니다.</p>
<p>노출된다면 악의적인 사용자가 인증 토큰을 획득하여 API를 사용할 수 있습니다.</p>
<p>만약, 노출되었다면 즉시 KOS 팀을 통해 새로운 API Key를 발급 받아야 합니다.</p>
</Callout>

인증 토큰을 발급 받기 위해선, KOS 팀으로 부터 전달 받은 API Key가 필요합니다.

[인증 토큰 교환](/docs/openapi/exchange-token) API를 통해 인증 토큰을 발급 받을 수 있습니다.

## 인증 흐름

1. KOS 팀으로부터 API Key를 발급받습니다.
2. 서버 사이드에서 [인증 토큰 교환](/docs/openapi/exchange-token) API에 API Key를 전달하여 인증 토큰을 발급받습니다.
3. 발급받은 인증 토큰을 이후 API 요청의 `Authorization` 헤더에 담아 호출합니다.

<Callout type="info">
<p>API Key 발급과 인증 토큰 교환, 인증 토큰을 사용하는 모든 호출은 서버 사이드에서만 이루어져야 합니다.</p>
</Callout>

## 토큰 유효 기간

인증 토큰은 일정 시간이 지나면 만료됩니다. 유효 기간은 KOS 정책에 따라 달라질 수 있습니다.

## 토큰 만료 처리

토큰이 만료된 상태에서 API를 호출하면 `401` 상태 코드가 반환됩니다.

이 경우, [인증 토큰 교환](/docs/openapi/exchange-token) API를 다시 호출하여 새로운 토큰을 발급받은 뒤 요청을 재시도하세요.

## 토큰 관리 전략

매 요청마다 토큰을 새로 교환하지 않고, 다음 전략으로 관리하기를 권장합니다.

- **재사용**: 발급받은 토큰을 서버 사이드의 메모리나 캐시에 보관하고 재사용합니다.
- **401 대응**: API 요청이 `401` 응답을 반환하면 토큰을 다시 교환하여 갱신하고 실패한 요청을 재시도합니다.

토큰 값을 직접 파싱해 만료 여부를 판단하지 말고, API의 `401` 응답으로 만료를 처리하세요.

## API Key 관리

- API Key는 서버 환경 변수나 시크릿 저장소에 보관하며, 코드 저장소나 클라이언트에 포함하지 않습니다.
- API Key가 유출되었거나 유출이 의심되면 즉시 KOS 팀을 통해 새 API Key를 발급받습니다.

## 보안 주의

인증 관련을 제외한 모든 OpenAPI 요청은 `Authorization` 헤더에 인증 토큰(Auth Token)을 포함해야 합니다.

절대로 API Key와 인증 토큰을 클라이언트에 노출하지 마세요. 인증 토큰 교환도 브라우저나 모바일 클라이언트에서 수행하면 안 됩니다.

API Key와 Auth Token은 KOS Connect의 `appId`와 다릅니다. OpenAPI 인증 정보는 서버에서만 다루고, 노출되었다면 즉시 KOS 팀을 통해 새 API Key를 발급받아야 합니다.

## 엔드포인트

- [인증 토큰 교환](/docs/openapi/exchange-token.md): `POST /open/authorization/commands/exchange-token`