---
title: "인증"
description: "API 키를 사용하여 API 요청을 인증하고 자격 증명을 안전하게 관리하는 방법을 알아보세요."
---

# 인증

모든 Minds API 요청은 API 키를 사용하여 인증이 필요합니다. API 키는 귀하의 계정에 고유하며 자원에 대한 안전한 접근을 제공합니다.

## API 키 받기

1. Minds 계정에 로그인합니다.
2. **설정** → **API 키**로 이동합니다.
3. **새 API 키 생성**을 클릭합니다.
4. API 키를 즉시 복사합니다(다시 볼 수 없습니다!).

API 키는 `minds_`로 시작하며 다음과 같은 형식입니다: `minds_0000111122223333444455556666777788889999aaaabbbb`

## API 키 사용하기

모든 요청의 `Authorization` 헤더에 API 키를 포함시킵니다:

```bash
Authorization: Bearer minds_your_api_key_here
```

### 예제 요청

```bash
curl -X GET "https://getminds.ai/api/v1/api-keys" \
  -H "Authorization: Bearer minds_your_api_key"
```

## 보안 모범 사례

### 키를 비밀로 유지하기

- **절대** API 키를 버전 관리 시스템에 커밋하지 마세요.
- **절대** 공개 포럼이나 채팅에서 키를 공유하지 마세요.
- 키를 환경 변수나 안전한 금고에 저장하세요.
- 보안을 위해 정기적으로 키를 교체하세요.

### 환경 변수 사용하기

```bash
# Set your key as an environment variable
export MINDS_API_KEY="minds_your_api_key_here"

# Use it in requests
curl -X GET "https://getminds.ai/api/v1/api-keys" \
  -H "Authorization: Bearer $MINDS_API_KEY"
```

### 키를 정기적으로 교체하기

키가 유출된 것으로 의심되는 경우:

1. 새 API 키를 생성합니다.
2. 애플리케이션을 새 키로 업데이트합니다.
3. 이전 키를 삭제합니다.

## 인증된 사용자 식별하기

API 키가 유효한지 확인하고 어떤 계정에 속하는지 식별합니다:

```bash
GET /api/v1/auth/me
```

**응답:**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}
```

API 키와 연결된 사용자 ID를 반환합니다. 시작 시 또는 키를 교체한 후 자격 증명을 확인하는 데 유용합니다. 키가 없거나 유효하지 않은 경우 `401 Unauthorized`를 반환합니다.

## API 키 관리하기

### API 키 목록 보기

```bash
GET /api/v1/api-keys
```

메타데이터와 함께 API 키 목록을 반환합니다(실제 키 값은 반환되지 않음):

```json
[
  {
    "id": "key-id",
    "name": "prod",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "lastUsedAt": "2025-12-10T13:00:00.000Z"
  }
]
```

### 새 API 키 생성하기

```bash
POST /api/v1/api-keys
```

**헤더:**

```text
Content-Type: application/json
```

**요청 본문 (선택 사항):**

```json
{
  "name": "prod"
}
```

선택적 `name` 필드는 키에 대한 사람이 읽을 수 있는 레이블입니다(문자열, 1–100자). 목록 엔드포인트와 설정 UI에서 키를 식별하는 데 도움이 됩니다. 공백은 제거되며, 빈 값이나 누락된 값은 `null`로 저장됩니다. 빈 요청 본문도 허용되며 이름 없는 키를 생성합니다.

응답에는 실제 키가 포함됩니다(이때만 볼 수 있습니다):

```json
{
  "id": "new-key-id",
  "name": "prod",
  "key": "minds_0000111122223333444455556666777788889999aaaabbbb",
  "createdAt": "2025-12-10T12:00:00.000Z"
}
```

#### 이름이 있는 예제

```bash
curl -X POST "https://getminds.ai/api/v1/api-keys" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"prod"}'
```

⚠️ **중요:** `key` 값을 즉시 저장하세요! 다시 가져올 수 없습니다.

### API 키 삭제하기

```bash
DELETE /api/v1/api-keys/{keyId}
```

성공 시 빈 본문과 함께 `204 No Content`을 반환합니다.

## 인증 오류

### 401 권한 없음

API 키가 누락되었거나 유효하지 않습니다.

```json
{
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Invalid or missing API key"
}
```

**해결 방법:**

- `Authorization` 헤더가 포함되었는지 확인하세요.
- API 키가 정확한지 확인하세요.
- `Bearer` 접두사를 사용하고 있는지 확인하세요.
- 이전 키가 삭제된 경우 새 키를 생성하세요.

## 요금제 기반 접근

API 접근은 유료 요금제에서 지원되며 제품에 표시되거나 계약으로 합의된 리소스, 응답 및 워크스페이스 한도의 적용을 받습니다. 한도를 코드에 고정하지 말고 구조화된 `PLAN_LIMIT` 및 `plan_limited` 응답을 처리하세요. Individual 요금제는 API 페이로드에서 `"premium"`으로 표시됩니다.

[요금제 보기](/pricing)