---
title: API 인증
description: 범위가 지정된 개인 액세스 토큰 또는 OAuth bearer로 인증하고 조직 식별과 자격 증명 폐기를 알아봅니다.
species: reference
---
# API 인증

모든 API 요청에 bearer 자격 증명을 보내세요.

```bash fragment
Authorization: Bearer pat_...
```

bearer 자격 증명은 서버 측에 보관하세요. API 자격 증명이 없거나 유효하지 않아도 요청이 브라우저 쿠키를 대신 사용하지는 않습니다.

## 개인 액세스 토큰

PAT는 `pat_`로 시작합니다. Supernova는 비밀 값을 한 번만 표시하고 해시만 저장합니다. 비밀 값을 잃어버리면 복구할 수 없으므로 새 토큰을 생성하세요.

각 PAT는 사용자 1명과 조직 1개에 속하며, 명시적인 권한 범위 집합과 선택적인 만료일을 기록합니다. 폐기는 다음 요청부터 적용됩니다.

## 서비스 키

서비스 키는 `nsk_`로 시작하며 개인이 아닌 조직에 속합니다. 작업, 스크립트, 작성자가 퇴사한 뒤에도 계속 실행되어야 하는 용도에 사용하세요.

```bash fragment
Authorization: Bearer nsk_...
```

조직 관리자는 **설정 → 쿼리 액세스**에서 키를 만들고 이름을 지정한 다음 비밀 값을 복사합니다. PAT와 마찬가지로 비밀 값은 한 번만 표시되며 해시만 저장됩니다. 키 폐기는 다음 요청부터 적용됩니다.

키는 읽기 전용이며 정확히 `query:read`와 `data:read` 권한만 가집니다. 쿼리를 실행하고 카탈로그를 읽을 수 있으며 이 권한을 확장할 수는 없습니다. 키는 권한이 부여된 테이블만 읽습니다. 거부 응답은 [쿼리](/docs/api/queries)를 참고하세요.

조직에서 테이블 권한을 활성화한 뒤에 키를 사용할 수 있습니다. 이 권한 부여가 키로 읽을 수 있는 테이블을 결정하기 때문입니다. 그 전에는 유효한 키도 `403 service_key_permissions_off`로 거부됩니다.

## OAuth 액세스 토큰

OAuth는 PKCE를 사용하는 인가 코드 방식을 따릅니다. 동의 화면에는 조직과 요청된 권한 범위가 표시됩니다. 액세스 토큰에는 공개 API 대상, 허용된 발급자, 유효한 `jti`, 엔드포인트에 필요한 권한 범위가 있어야 합니다.

토큰의 주체가 호출자 주체가 됩니다. 같은 조직 안에서도 멱등성과 호출자 요청 빈도 제한은 주체별로 구분됩니다.

## 신원 확인

```endpoint
GET /whoami
```

인증된 주체, 조직, 역할, 부여된 권한 범위를 반환합니다. 로그인하거나 프로필을 선택한 뒤 호출하여 자격 증명이 어느 테넌트를 대상으로 하는지 확인하세요.

```endpoint
GET /orgs
```

자격 증명 계약에서 선택을 허용하는 경우 인증된 사용자가 사용할 수 있는 조직을 반환합니다.

## 권한 범위 목록

| 권한 범위 | 기능 |
|---|---|
| `query:read` 또는 `query:execute` | 호환성 전환 기간의 쿼리 및 쿼리 작업 리소스 |
| `data:read` | 카탈로그, 소스 읽기, 로그, 사용량 |
| `apps:manage` | 소스 및 PAT 관리 |
| `models:read`, `models:write` | 모델 리소스 |
| `files:write`, `files:admin` | 데이터 저장소 변경 |
| `members:manage` | 조직 구성원 관리 |
| `data:policies:manage` | 데이터 정책 관리 |

유효한 자격 증명이라도 필요한 권한 범위가 없으면 엔드포인트는 `403 insufficient_scope`로 거부합니다.