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

# 자체 키 사용（BYOK）

> ARouter를 통해 자신의 제공업체 API 키를 사용합니다. BYOK는 귀하의 자격 증명을 사용하여 제공업체로 직접 요청을 라우팅합니다 — ARouter의 토큰 비용 마진 없음.

<Note>
  BYOK는 현재 개발 중입니다. 베타 참여를 위해 [support@arouter.ai](mailto:support@arouter.ai)로 문의하세요.
</Note>

Bring Your Own Key（BYOK）를 사용하면 ARouter에 자신의 제공업체 API 키를 등록할 수 있습니다. 등록된 키가 있는 제공업체로 요청이 라우팅될 때, ARouter는 공유 키 풀 대신 귀하의 키를 사용합니다.

**장점：**

* **마진 없음** — 제공업체 정가로 직접 지불, 토큰 비용 마진 없음
* **자체 할당량** — 요청이 ARouter의 공유 풀이 아닌 귀하의 제공업체 요금 제한에 카운트
* **자체 데이터 정책** — 기존 제공업체 계약 및 데이터 조건 적용
* **통합 게이트웨이** — ARouter의 라우팅, 폴백, 관찰 가능성을 상위에서 계속 활용

***

## BYOK 작동 방식

```
귀하의 요청 → ARouter 게이트웨이 → [경로 선택] → 제공업체 API（귀하의 키 사용）
```

1. ARouter 대시보드에서 제공업체 API 키 등록
2. ARouter가 해당 제공업체로 요청을 라우팅할 때 귀하의 키로 대체
3. 토큰 비용은 계정에 청구되지 않음（ARouter 서비스 요금만, 해당하는 경우）
4. 응답에 `usage.is_byok: true` 반환

***

## 키 등록

[ARouter 대시보드](https://arouter.ai/settings/byok)에서 제공업체 키를 추가합니다.

지원되는 제공업체 및 키 형식：

| 제공업체             | 키 형식             | 대시보드 레이블             |
| ---------------- | ---------------- | -------------------- |
| OpenAI           | `sk-...`         | OpenAI API Key       |
| Anthropic        | `sk-ant-...`     | Anthropic API Key    |
| Google (Gemini)  | `AIza...`        | Google AI Studio Key |
| Azure OpenAI     | 엔드포인트 + 키        | Azure OpenAI         |
| AWS Bedrock      | 액세스 키 + 시크릿 + 리전 | AWS Bedrock          |
| Google Vertex AI | 서비스 계정 JSON      | Google Vertex AI     |

***

## BYOK와 제공업체 순서 결합

BYOK와 `provider.order`를 결합하여 키가 언제 사용될지 제어합니다：

```json theme={null}
{
  "model": "openai/gpt-5.4",
  "messages": [{"role": "user", "content": "Hello"}],
  "provider": {
    "order": ["OpenAI"]
  }
}
```

`OpenAI`가 순서 목록에 있고 OpenAI BYOK 키가 등록된 경우, ARouter는 해당 제공업체에 귀하의 키를 자동으로 사용합니다.

### 부분 BYOK

일부 제공업체에는 키를 등록하고 나머지는 ARouter의 공유 풀을 사용할 수 있습니다：

```json theme={null}
{
  "model": "anthropic/claude-sonnet-4.6",
  "provider": {
    "order": ["Anthropic", "AWS Bedrock"]
  }
}
```

Anthropic BYOK 키가 있으면 귀하의 키로 Anthropic을 먼저 시도합니다. AWS Bedrock 키가 있으면 다음에 시도합니다. 그렇지 않으면 ARouter가 공유 풀로 폴백합니다.

***

## Azure OpenAI

Azure OpenAI 엔드포인트와 키를 등록합니다：

```json theme={null}
{
  "provider_name": "Azure",
  "azure_endpoint": "https://your-resource.openai.azure.com",
  "azure_api_key": "your-azure-key",
  "azure_deployment": "gpt-5-4"
}
```

그런 다음 라우팅합니다：

```json theme={null}
{
  "model": "openai/gpt-5.4",
  "provider": {
    "order": ["Azure"]
  }
}
```

***

## AWS Bedrock

두 가지 인증 옵션：

**옵션 1: Bedrock API 키（권장）**

```json theme={null}
{
  "provider_name": "Bedrock",
  "aws_access_key_id": "AKIA...",
  "aws_secret_access_key": "your-secret",
  "aws_region": "us-east-1"
}
```

**옵션 2: AWS 자격 증명**

```json theme={null}
{
  "provider_name": "Bedrock",
  "aws_credentials": {
    "access_key_id": "AKIA...",
    "secret_access_key": "...",
    "session_token": "...",
    "region": "us-east-1"
  }
}
```

***

## Google Vertex AI

```json theme={null}
{
  "provider_name": "VertexAI",
  "vertex_service_account": {
    "type": "service_account",
    "project_id": "your-project",
    "private_key_id": "...",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...",
    "client_email": "your-sa@your-project.iam.gserviceaccount.com"
  }
}
```

***

## BYOK 요청 식별

귀하의 키가 사용된 경우 응답의 `usage` 객체에 `is_byok: true`가 포함됩니다：

```json theme={null}
{
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 45,
    "total_tokens": 165,
    "cost": 0.00,
    "is_byok": true
  }
}
```

`is_byok: true`인 경우 `usage.cost`는 귀하의 직접 제공업체 비용（ARouter 마진 없음）을 반영합니다.

***

## 키 우선순위 및 폴백

| 시나리오                                 | 동작                                                |
| ------------------------------------ | ------------------------------------------------- |
| 제공업체의 BYOK 키가 등록됨                    | 귀하의 키 사용                                          |
| BYOK 키가 등록됐지만 제공업체 이용 불가             | ARouter 공유 풀로 폴백（`allow_fallbacks: false`가 아닌 경우） |
| 해당 제공업체의 BYOK 키 없음                   | ARouter 공유 풀 사용                                   |
| `allow_fallbacks: false` + BYOK 키 없음 | 404로 요청 실패                                        |

***

## BYOK 문제 디버깅

대시보드의 활동 페이지에서 각 요청에 사용된 키를 확인하세요. 일반적인 오류：

| 오류                 | 원인               | 수정 방법                              |
| ------------------ | ---------------- | ---------------------------------- |
| `401 Unauthorized` | 잘못되거나 만료된 제공업체 키 | 대시보드 설정에서 키 교체                     |
| `403 Forbidden`    | 키에 필요한 권한 없음     | 제공업체 IAM 설정 확인                     |
| `quota_exceeded`   | 제공업체 할당량 소진      | 제공업체 플랜 업그레이드 또는 BYOK 제거 후 공유 풀 사용 |