Overview

Manager API Overview

This document describes the Management API capabilities, including authentication methods, API usage, and organization-specific behavior.

The current Management API provides two categories of functionality:

1. Manage Management API Keys with a user JWT
2. Query balance and usage with a Management API Key

Basic Information

• Base URL: /api/v1/portal
• Content-Type: application/json
• Character Encoding: UTF-8

Response Format

Success response:

{
  "meta": {
    "code": 0,
    "message": "success",
    "request_id": "xxx"
  },
  "data": {}
}

Error response:

{
  "meta": {
    "code": 400,
    "message": "error message",
    "request_id": "xxx"
  },
  "data": null
}

Authentication

1. JWT Authentication

Used for creating, listing, updating, deleting, revoking, and restoring Management API Keys.

Example headers:

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

2. Management API Key Authentication

Used for balance and usage queries.

Example headers:

Authorization: Bearer <management_api_key>

Management API Keys use the following format:

sk_mg_<64 hex characters>

Example:

sk_mg_a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789

Organization Behavior

• Creating an organization-level API Key requires the caller to be an organization admin.
• When querying with a Management API Key, the request uses the key-bound org_id by default.
• When an organization admin uses an organization-level Management API Key for usage queries, they can additionally filter by user_id to inspect a specific member.

Quick Start

1. Create a Management API Key

curl -X POST 'https://your-domain/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"]
  }'

Example response:

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

Notes:

• The full api_key is returned only once when creation succeeds.
• Save it immediately after creation.

2. Query Balance with a Management API Key

curl 'https://your-domain/api/v1/portal/management/balance?currency_code=CNY' \
  -H 'Authorization: Bearer <management_api_key>'

3. Query Usage with a Management API Key

curl 'https://your-domain/api/v1/portal/management/usage?start_time=1710000000&end_time=1710086400&page=1&pagesize=20' \
  -H 'Authorization: Bearer <management_api_key>'

API List

Endpoint	Method	Description
/management/api-keys	POST	Create API Key
/management/api-keys	GET	List API Keys
/management/api-keys/:api_key_id	PUT	Update API Key
/management/api-keys/:api_key_id	DELETE	Delete API Key
/management/api-keys/revoke	POST	Revoke API Key
/management/api-keys/restore	POST	Restore API Key
/management/balance	GET	Query Account Balance
/management/usage	GET	Query Usage Details

Notes

• API Keys are only displayed once after creation. Store them securely.
• Rotate API Keys regularly and avoid using permanent keys.
• If a key is lost, delete it and create a new one.
• The same user can create at most 10 active keys within the same organization.

Related APIs

• API Keys Management - Create, list, update, delete, revoke, and restore API Keys
• Balance - Query account balance
• Usage - Query usage details