Reporting Access Key

Reporting Access Key は、利用量の照合に使うダッシュボード管理の読み取り専用キーです。通常のモデル API キーを公開せずに、社内のレポーティングサービス、会計ワークフロー、BI パイプラインから API キー情報、トークン使用量、タスク履歴、コストデータを参照できます。

1. 利用シーン

次のようなケースで使用します。

• Reconcile invoice totals with task-level usage records
• Export usage data to internal BI, FinOps, or monitoring systems
• Track token consumption and cost by API key, model, task type, status, or day
• Investigate individual task records without sharing operational dashboard access

これはモデル呼び出し用のキーではありません。利用できるのは /api/open/v1/* のレポーティング API のみです。

2. キーの作成と管理

ダッシュボードで次のページを開きます。

/dashboard/apikeys

In the Reporting Access Key card:

1. Click Generate to create the key.
2. Copy the key and store it in a secure secret manager.
3. Use Copy when you need to retrieve the full value again.
4. Use Revoke to disable the current key.

セキュリティ仕様：

• The page shows only a masked key by default.
• The full key is fetched only when you click Copy.
• The full key should not be stored in localStorage, analytics, screenshots, tickets, or client logs.
• Each user currently has at most one active Reporting Access Key.
• Revoked keys stop working immediately and are not hard-deleted.

3. 認証

Authorization ヘッダーに Reporting Access Key を指定します。

Authorization: Bearer <REPORTING_ACCESS_KEY>
Accept: application/json

レスポンスは共通のエンベロープ形式です。

{
  "code": 200,
  "msg": "",
  "data": {}
}

4. エンドポイント

Base URL:

https://reachapi.ai/api/open/v1

ローカル開発では次を使用できます。

http://localhost:3000/api/open/v1

5. API キー一覧

curl -sS "https://reachapi.ai/api/open/v1/apikeys?page=1&page_size=20&status=active" \
  -H "Authorization: Bearer <REPORTING_ACCESS_KEY>"

Query parameters:

Example response:

{
  "code": 200,
  "msg": "",
  "data": {
    "total": 3,
    "page": 1,
    "page_size": 20,
    "items": [
      {
        "apikey_id": "ak_123",
        "apikey_name": "Production gateway",
        "status": "active",
        "created_at": "2026-06-27T08:00:00.000Z",
        "last_used_at": "2026-06-27T09:15:00.000Z",
        "hourly_limit_usd": "5.00000000",
        "daily_limit_usd": "20.00000000",
        "total_limit_usd": "100.00000000",
        "quota_timezone": "Asia/Shanghai"
      }
    ]
  }
}

各項目の内容：

6. 利用量サマリー

curl -sS "https://reachapi.ai/api/open/v1/usage/summary?start_date=2026-06-01&end_date=2026-06-07&timezone=Asia/Shanghai" \
  -H "Authorization: Bearer <REPORTING_ACCESS_KEY>"

Query parameters:

The response includes request counts, success/error counts, token buckets, actual_credits, and total_amount in USD string format.

7. 日次集計

curl -sS "https://reachapi.ai/api/open/v1/usage/daily?start_date=2026-06-01&end_date=2026-06-07&group_by=apikey,model" \
  -H "Authorization: Bearer <REPORTING_ACCESS_KEY>"

group_by supports:

8. タスク一覧

curl -sS "https://reachapi.ai/api/open/v1/usage/tasks?start_date=2026-06-01&end_date=2026-06-07&page=1&page_size=50" \
  -H "Authorization: Bearer <REPORTING_ACCESS_KEY>"

The task list supports the same filters as usage/summary. The date range is limited to 7 days to keep reconciliation queries predictable.

Each item includes:

9. タスク詳細

curl -sS "https://reachapi.ai/api/open/v1/usage/tasks/task_123" \
  -H "Authorization: Bearer <REPORTING_ACCESS_KEY>"

The detail endpoint returns one task with amount, token, and error information. It is useful when reconciling a single customer ticket, provider job, or billing row.

10. エラー

11. アクセスログ

Customer calls made with a Reporting Access Key are written to a dedicated access-key usage log on the server.

The log is designed for operational review and does not store secrets. It records only redacted request metadata such as event name, request ID, key prefix, user ID, method, path, safe query parameters, status code, duration, IP, user agent, and error code.

It does not record full access keys, Authorization headers, cookies, passwords, key hashes, ciphertext, or database connection strings.