---
title: API 認証
description: スコープ付きの個人アクセストークンまたは OAuth ベアラートークンで認証し、組織の識別と失効の仕組みを確認します。
species: reference
---
# API 認証

すべての API リクエストで、ベアラー認証情報を送信してください。

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

ベアラー認証情報はサーバー側で保持してください。API 認証情報がない、または無効なリクエストが、ブラウザーの Cookie にフォールバックすることはありません。

## 個人アクセストークン

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` で拒否します。