Reporting Access Key

Reporting Access Key is a dashboard-managed key for read-only usage reconciliation. It lets an internal reporting service, finance workflow, or BI pipeline query API key metadata, token usage, task history, and cost data without exposing normal model API keys.

1. When to use it

Use a Reporting Access Key when you need to:

• 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

It is not a model invocation key. It only authorizes the /api/open/v1/* reporting endpoints documented below.

2. Create and manage the key

Open the dashboard and go to:

/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.

Security behavior:

• 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. Authentication

Send the Reporting Access Key in the Authorization header:

Authorization: Bearer <REPORTING_ACCESS_KEY>
Accept: application/json

All responses use the platform envelope:

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

4. Endpoints

Base URL:

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

For local development, use your local application host:

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

5. List API keys

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"
      }
    ]
  }
}

Each item includes:

6. Usage summary

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. Daily breakdown

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. Task list

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. Task detail

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. Errors

11. Access log behavior

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.