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

# 인증 · 시크릿 · 감사 로그

> API 키, 시크릿 관리, PII 필터, 감사 로그가 Bridger에서 어떻게 처리되는지 살펴봅니다.

Bridger Gateway는 공공데이터와 직접 등록한 API를 한 도메인으로 노출하는 만큼, 보안 경계가 가장 중요한 책임입니다.
다음 4개 레이어가 모든 요청에 적용됩니다.

<CardGroup cols={2}>
  <Card title="인증" icon="key">
    API Key / OAuth 2.0 으로 호출자 식별.
  </Card>

  <Card title="시크릿 관리" icon="lock">
    공공데이터 ServiceKey, BYOAPI 토큰을 Vault에 격리.
  </Card>

  <Card title="PII 필터" icon="user-shield">
    응답에서 개인정보 패턴을 마스킹.
  </Card>

  <Card title="감사 로그" icon="clipboard-check">
    누가 · 언제 · 어떤 도구를 호출했는지 추적.
  </Card>
</CardGroup>

## 1. 인증

### API Key

가장 단순한 방식이며 대부분의 사용자가 사용합니다.

```bash theme={null}
curl -X POST https://mcp.datari.kr/mcp \
  -H "x-api-key: $DATA_BRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

* 헤더: `x-api-key` 또는 `Authorization: Bearer <key>`
* 키는 [admin.datari.kr](https://admin.datari.kr) → **Settings → API Keys**에서 발급/회수
* 키는 필요할 때 즉시 회수할 수 있습니다.

### OAuth 2.0

조직 단위 권한 관리가 필요할 때 사용합니다. Authorization Code · Client Credentials 두 가지 흐름을 지원하며 자세한 스펙은 [API Reference → Authentication](/api-reference/authentication)에서 다룹니다.

## 2. 시크릿 관리

Bridger가 처리하는 시크릿은 다음 세 종류입니다.

| 종류                 | 예시                            | 저장 위치                      |
| ------------------ | ----------------------------- | -------------------------- |
| 공공데이터 ServiceKey   | `data.go.kr` 발급 키             | Vault (Gateway 측)          |
| BYOAPI Upstream 토큰 | 사용자 API의 OAuth/HTTP Header 토큰 | Vault per-tenant 격리        |
| Bridger API Key    | 호출자 인증 키 (`dk_live_…`)        | DB(해시) + 토큰 자체는 발급 시 1회 노출 |

**원칙**

* 시크릿은 절대 로그·응답·MCP 메타데이터에 포함되지 않습니다.
* 공공데이터 미들웨어가 ServiceKey를 자동 주입하므로 사용자는 키를 다룰 필요가 없습니다.
* BYOAPI 등록 시 사용자가 입력한 토큰은 Vault에 암호화 저장 후 즉시 메모리에서 제거됩니다.

## 3. PII 필터

응답 본문(중첩 JSON 포함)에서 다음 패턴을 자동 마스킹합니다.

* 주민등록번호 (`\d{6}-\d{7}` → `******-*******`)
* 휴대전화 번호 (`***-****-****`)
* 신용카드 번호 (13\~19자리 숫자열 → `****-****-****-****`)
* 이메일 (`***@***.***`)

## 4. 감사 로그

모든 `tools/call`은 다음 필드와 함께 기록됩니다.

```json theme={null}
{
  "timestamp": "2026-04-30T07:31:09.412Z",
  "type": "tool_call",
  "action": "tools/call",
  "userId": "usr_...",
  "tenantId": "tnt_...",
  "tool": "getweatherforecast",
  "toolId": "@datari/weather-ultra-shortcast",
  "params": { "...": "마스킹 적용" },
  "status": 200,
  "duration": 312,
  "success": true
}
```

| 필드                    | 설명                            |
| --------------------- | ----------------------------- |
| `timestamp`           | ISO 8601 기록 시각                |
| `userId` / `tenantId` | 호출자·테넌트 식별자                   |
| `tool` / `toolId`     | 호출된 도구 이름과 등록 ID              |
| `params`              | 입력 파라미터 (PII·시크릿 필드 마스킹 후 저장) |
| `status`              | upstream HTTP 상태 코드           |
| `duration`            | 처리 시간(ms)                     |
| `success`             | 성공 여부                         |

* 입력 파라미터의 민감 필드는 마스킹 후 저장되며, 시크릿은 절대 기록되지 않습니다.
* 시크릿 작업(`secret.store`·`secret.read`·`secret.rotate`·`secret.revoke`)은 값 대신 불투명 참조(`opaqueRef`)만 별도 기록합니다.
* [admin.datari.kr](https://admin.datari.kr) → **Audit**에서 `GET /api/v1/audit/logs`로 검색·다운로드합니다.

## 5. 네트워크 경계

* 모든 트래픽은 TLS 1.3 (와일드카드 인증서 `*.datari.kr`, cert-manager + Let's Encrypt).
* Gateway는 Kubernetes NetworkPolicy `default-deny`를 기본으로 하며, 명시적으로 허용된 ingress 출처에서만 도달 가능합니다.
* Pod는 `runAsNonRoot` + `readOnlyRootFilesystem` + 최소 권한 SecurityContext.

## 다음 단계

<CardGroup cols={2}>
  <Card title="API Reference: Auth" icon="key" href="/api-reference/authentication">
    헤더, 에러 코드, OAuth 흐름.
  </Card>

  <Card title="아키텍처" icon="diagram-project" href="/concepts/architecture">
    어디에서 인증·미들웨어·로그가 실행되는지.
  </Card>
</CardGroup>