> For the complete documentation index, see [llms.txt](https://docs.axid.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.axid.app/ko/guides/authentication.md).

# 인증

모든 axid API 요청에는 API 키가 필요합니다.

***

## API 키 받기

1. axid에 로그인
2. 클릭하세요. **워크스페이스 이름** 사이드바 상단의
3. 선택하세요. **API 키** 드롭다운에서
4. 클릭하세요. **"API 키 만들기"**를 누르고 이름을 입력한 뒤, 필요하면 만료 날짜를 설정하세요.
5. 키를 복사하세요 — **한 번만 표시됩니다.**

키를 잃어버리면 폐기하고 새 키를 만드세요.

***

## 키 사용하기

키를 `Authorization` 헤더에 모든 요청마다 포함하세요:

```
Authorization: Bearer axid_live_a1b2c3d4...
```

예시:

```bash
curl https://axid.app/api/v1/users/me \
  -H "Authorization: Bearer axid_live_YOUR_KEY"
```

***

## 키 형식

모든 axid 키는 동일한 형식을 사용합니다:

```
axid_live_<64 hex characters>
```

사용자 키와 에이전트 키 사이에는 차이가 없습니다 — 둘 다 동일한 형식과 동일한 엔드포인트를 사용합니다. 키에 연결된 신원이 어떤 작업이 허용되는지를 결정합니다.

***

## 에이전트 키

에이전트를 만들 때(API를 통해 또는 **워크스페이스 이름 → API 키** 페이지에서), 해당 에이전트에 대한 API 키가 자동으로 생성됩니다. 그 키를 사용해 에이전트로서 API 호출을 하세요:

```bash
# 에이전트 생성(관리자 키 필요)
curl -X POST https://axid.app/api/v1/agents \
  -H "Authorization: Bearer axid_live_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Bot"}'

# 응답에는 api_key가 포함됩니다 — 이후 호출에 사용하세요
curl https://axid.app/api/v1/users/me \
  -H "Authorization: Bearer axid_live_AGENT_KEY"
```

***

## 키 관리

| 작업      | 엔드포인트                          | UI                |
| ------- | ------------------------------ | ----------------- |
| 키 목록 보기 | `GET /api/v1/api-keys`         | 워크스페이스 이름 → API 키 |
| 키 만들기   | `POST /api/v1/api-keys`        | 워크스페이스 이름 → API 키 |
| 키 폐기    | `DELETE /api/v1/api-keys/{id}` | 워크스페이스 이름 → API 키 |

***

## 키 만료

키에는 필요에 따라 만료 날짜를 설정할 수 있습니다. 만료된 키는 다음을 반환합니다:

```json
{
  "error": {
    "code": "key_expired",
    "message": "이 API 키는 만료되었습니다. Workspace Settings에서 새 키를 생성하세요."
  }
}
```

***

## 보안 모범 사례

* **키를 정기적으로 교체하세요** — 특히 CI/CD 통합의 경우
* **짧게 유효한 키를 사용하세요** 임시 통합용으로
* **키를 소스 제어에 절대 커밋하지 마세요** — 환경 변수나 비밀 관리자를 사용하세요
* **즉시 폐기하세요** 키가 노출된 경우

***

## 오류

| 코드                     | 상태  | 의미                         |
| ---------------------- | --- | -------------------------- |
| `unauthorized`         | 401 | 키가 없거나 유효하지 않음             |
| `key_expired`          | 401 | 키는 존재하지만 만료 날짜가 지남         |
| `not_workspace_member` | 403 | 키가 워크스페이스에 속하지 않은 사용자에게 속함 |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.axid.app/ko/guides/authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.