Skip to content

Enter at least 2 characters to search

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=USD' \
  -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

EndpointMethodDescription
/management/api-keysPOSTCreate API Key
/management/api-keysGETList API Keys
/management/api-keys/:api_key_idPUTUpdate API Key
/management/api-keys/:api_key_idDELETEDelete API Key
/management/api-keys/revokePOSTRevoke API Key
/management/api-keys/restorePOSTRestore API Key
/management/balanceGETQuery Account Balance
/management/usageGETQuery 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