> 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.

# Authentication

## Authentication Method

All API requests, except those related to authentication, require an Auth Token.

The Auth Token must be included in the HTTP Header.

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

_\* A prefix such as `Bearer` is not required._

<details>
<summary>Key Concepts</summary>
<dl>
<dt>API Key</dt>
<dd><strong>Definition:</strong> A server-side authentication key issued to the clinic by the KOS team.<br /><strong>Description:</strong> This is the input value used to obtain an authentication token. It must not be exposed to the client and should only be used server-side.</dd>
<dt>Auth Token</dt>
<dd><strong>Definition:</strong> A token sent in the <code>Authorization</code> header with each API request.<br /><strong>Description:</strong> Required for all requests except authentication-related APIs. The token may expire after a certain period of time, and calling with an expired token will return a <code>401</code> response.</dd>
<dt>Auth Token Exchange</dt>
<dd><strong>Definition:</strong> A server-side process for exchanging an API Key for an authentication token.<br /><strong>Description:</strong> This must only be performed server-side, as executing it on the client side may expose the API Key.</dd>
<dt>Authorization Header</dt>
<dd><strong>Definition:</strong> An HTTP header used to transmit the authentication token.<br /><strong>Description:</strong> Only the authentication token is included as the value; no prefix such as <code>Bearer</code> is added.</dd>
</dl>
</details>

<Callout type="danger">
<p><strong>Never expose your API Key or Auth Token to the client.</strong></p>
<p>Take care that they are not exposed to or stored on the client.</p>
<p>Auth Token exchange must also never be performed on the client side.</p>
<p>If exposed, a malicious user could obtain the Auth Token and use the API.</p>
<p>If exposed, you must immediately obtain a new API Key through the KOS team.</p>
</Callout>

To obtain an Auth Token, you need the API Key provided by the KOS team.

You can obtain an Auth Token through the [Auth Token Exchange](/docs/openapi/exchange-token) API.

## Authentication Flow

1. Obtain an API Key from the KOS team.
2. On the server side, pass the API Key to the [Auth Token Exchange](/docs/openapi/exchange-token) API to obtain an Auth Token.
3. Include the obtained Auth Token in the `Authorization` header of subsequent API requests.

<Callout type="info">
<p>API Key issuance, Auth Token exchange, and all calls that use the Auth Token must be performed on the server side only.</p>
</Callout>

## Token Validity Period

The Auth Token expires after a certain time. The validity period may vary according to KOS policy.

## Token Expiration Handling

If you call the API with an expired token, a `401` status code is returned.

In this case, call the [Auth Token Exchange](/docs/openapi/exchange-token) API again to obtain a new token, then retry the request.

## Token Management Strategy

Rather than exchanging a new token for every request, we recommend managing tokens with the following strategy.

- **Reuse**: Store the obtained token in server-side memory or cache and reuse it.
- **401 Handling**: When an API request returns a `401` response, exchange the token again to refresh it and retry the failed request.

Do not parse the token value to determine expiration; handle expiration via the API's `401` response.

## API Key Management

- Store the API Key in server-side environment variables or a secret store, and do not include it in code repositories or on the client.
- If the API Key is leaked or a leak is suspected, immediately obtain a new API Key through the KOS team.

## Security Notes

Except for authentication APIs, every OpenAPI request must include an Auth Token in the `Authorization` header.

Never expose the API Key or Auth Token to client code. Token exchange must not run in a browser or mobile client.

API Keys and Auth Tokens are different from a KOS Connect `appId`. Keep OpenAPI credentials server-side, and if they are exposed, request a new API Key from the KOS team immediately.

## Endpoints

- [Exchange authentication token](/en/docs/openapi/exchange-token.md): `POST /open/authorization/commands/exchange-token`