API Keys Management

API Keys Management

Manage Management API Keys using JWT authentication. These APIs allow you to create, list, update, delete, revoke, and restore API Keys.

Authentication

JWT authentication is required for all API Key management operations.

Authorization: Bearer <access_token>
Content-Type: application/json

Create API Key

Create a new Management API Key.

Request

POST /management/api-keys

Request Body

{
  "org_id": "0",
  "name": "finance-dashboard",
  "description": "Used for finance dashboard queries",
  "expires_at": 0,
  "scopes": ["balance:read", "usage:read"]
}

Field Descriptions

Field	Type	Required	Description
org_id	string	No	Organization ID. For personal scope, omit it or use the default value
name	string	Yes	Name, 1 to 100 characters
description	string	No	Description, up to 500 characters
expires_at	int64	No	Unix timestamp. 0 means never expires
scopes	string[]	No	Scope list. Request validation limits each item to 1 to 50 characters; logic currently allows up to 10 items

Notes

• If expires_at is greater than 0, it must be later than the current time.
• The same user can create at most 10 active keys within the same organization.
• The full api_key is returned only once when creation succeeds. Save it immediately.

Response Example

{
  "meta": {
    "code": 0,
    "message": "success",
    "request_id": "xxx"
  },
  "data": {
    "api_key": "sk_mg_xxx",
    "id": "4e5f2a15-b9a1-498d-8c3e-f7f2608a1111",
    "org_id": "0",
    "name": "finance-dashboard",
    "description": "Used for finance dashboard queries",
    "status": "active",
    "display": "sk_mg_a1b2c3d4...5678abcd",
    "last_used_at": 0,
    "expires_at": 0,
    "created_at": 1710000000,
    "scopes": ["balance:read", "usage:read"]
  }
}

Request Examples

cURL

curl -X POST 'https://portal-api.r9s.ai/api/v1/portal/management/api-keys' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "finance-dashboard",
    "description": "Used for finance dashboard queries",
    "expires_at": 0,
    "scopes": ["balance:read", "usage:read"]
  }'

List API Keys

List all Management API Keys for the authenticated user.

Request

GET /management/api-keys

Query Parameters

Parameter	Type	Required	Description
status	string	No	Allowed values: active, disabled, revoked
page	int	No	Default is 1
per_page	int	No	Default is 20, maximum is 100

Response Example

{
  "meta": {
    "code": 0,
    "message": "success",
    "request_id": "xxx"
  },
  "data": {
    "list": [
      {
        "id": "4e5f2a15-b9a1-498d-8c3e-f7f2608a1111",
        "org_id": "0",
        "name": "finance-dashboard",
        "description": "Used for finance dashboard queries",
        "status": "active",
        "display": "sk_mg_a1b2c3d4...5678abcd",
        "last_used_at": 0,
        "expires_at": 0,
        "created_at": 1710000000,
        "scopes": ["balance:read", "usage:read"]
      }
    ],
    "total": 1
  }
}

Request Examples

cURL

curl -X GET 'https://portal-api.r9s.ai/api/v1/portal/management/api-keys?status=active&page=1&per_page=20' \
  -H 'Authorization: Bearer <access_token>'

Update API Key

Update an existing Management API Key.

Request

PUT /management/api-keys/:api_key_id

Request Body

{
  "name": "finance-dashboard-prod",
  "description": "Production finance dashboard"
}

Notes

• Only name and description can currently be updated.

Request Examples

cURL

curl -X PUT 'https://portal-api.r9s.ai/api/v1/portal/management/api-keys/4e5f2a15-b9a1-498d-8c3e-f7f2608a1111' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "finance-dashboard-prod",
    "description": "Production finance dashboard"
  }'

Delete API Key

Delete a Management API Key.

Request

DELETE /management/api-keys/:api_key_id

Notes

• Deletion is a soft delete.

Request Examples

cURL

curl -X DELETE 'https://portal-api.r9s.ai/api/v1/portal/management/api-keys/4e5f2a15-b9a1-498d-8c3e-f7f2608a1111' \
  -H 'Authorization: Bearer <access_token>'

Revoke API Key

Revoke a Management API Key.

Request

POST /management/api-keys/revoke

Request Body

{
  "api_key_id": "4e5f2a15-b9a1-498d-8c3e-f7f2608a1111"
}

Notes

• Only keys owned by the current user can be revoked.
• A revoked key will return an unauthorized error if used again for query APIs.

Request Examples

cURL

curl -X POST 'https://portal-api.r9s.ai/api/v1/portal/management/api-keys/revoke' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key_id": "4e5f2a15-b9a1-498d-8c3e-f7f2608a1111"
  }'

Restore API Key

Restore a revoked Management API Key.

Request

POST /management/api-keys/restore

Request Body

{
  "api_key_id": "4e5f2a15-b9a1-498d-8c3e-f7f2608a1111"
}

Notes

• Only keys in revoked status can be restored to active.

Request Examples

cURL

curl -X POST 'https://portal-api.r9s.ai/api/v1/portal/management/api-keys/restore' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key_id": "4e5f2a15-b9a1-498d-8c3e-f7f2608a1111"
  }'

Status Definitions

Status	Description
active	Available for normal use
disabled	Currently unavailable
revoked	Revoked and no longer usable for query APIs

Notes

• The currently exposed APIs support revoke and restore operations.
• The disabled status exists in listing and verification logic, but there is currently no user-facing API to set a key to disabled.

Common Errors

Scenario	Typical Error
Missing authentication info	unauthorized
Authorization header is not in Bearer format	unauthorized: invalid authorization format
Invalid API Key format	i18n error corresponding to invalid_format
API Key is revoked or expired	returns 401
Missing api_key_id	api_key_id is required
Non-admin attempts to create an organization-level key	permission denied

Related APIs

• Overview - Manager API overview and authentication
• Balance - Query account balance
• Usage - Query usage details