DataEyes AI — API Key Management API

Version: v1.0
Last Updated: 2026-07-22
Status: Verified in production

Overview

DataEyes AI Cloud provides a unified AI API gateway service. In addition to the web console, the platform exposes full-lifecycle management APIs for API keys (tokens), allowing you to programmatically create keys, query keys, adjust key quotas, enable/disable keys, and delete keys. These APIs are designed for enterprise scenarios such as automated key provisioning, quota allocation, and key rotation.

All endpoints in this document are management APIs — write operations or reads involving sensitive data. Keep your system access token strictly confidential. If you only need to query balance and usage, see the API Key & Quota Query API instead.

Base URLs

Purpose	URL
AI model calls & OpenAI-compatible API	`https://platform.dataeyes.ai`
Platform management API (this document)	`https://www.dataeyes.ai/apex`

Important: All endpoints in this document use https://www.dataeyes.ai/apex as the base URL (the www prefix is required). platform.dataeyes.ai serves only /v1/ model endpoints and does not provide management APIs.

Authentication

All endpoints use system access token authentication. Both headers below are required:

Authorization: Bearer <system_access_token>
apex-api-user: <user_numeric_id>

Header	Required	Description
`Authorization`	Yes	`Bearer <system_access_token>`. Generate and copy it in the console under "Personal Settings → Account Management → Security Settings"
`apex-api-user`	Yes	Your account's numeric ID. Contact the platform administrator to obtain it

The system access token and the numeric user ID must belong to the same account; a mismatch returns 401.
The system access token carries key-management privileges. Treat it with the highest sensitivity level and reset it immediately in the console if leaked.
All endpoints operate only on keys owned by the authenticated account.

Quota Units

The key quota field (remain_quota) uses the platform's internal quota unit:

500,000 quota units = 1 US dollar ($1)

remain_quota	USD
50000	$0.1
500000	$1
5000000	$10
50000000	$100

The dollar amounts shown on the console's "Token Management" page are converted from remain_quota.

When unlimited_quota is true, the key is not subject to quota limits and remain_quota is ignored.

Groups

A key's group field determines which channel resource pool the key routes to, and maps to a different billing multiplier. This is the most common pitfall when provisioning keys — please read it carefully.

The default group may have no available channel

When group is an empty string, the key uses the account's default group. On some accounts the default group has no channel bound, in which case calling a model with such a key returns:

{"error":{"code":"model_not_found","message":"分组 xxx 下模型 yyy 无可用渠道（distributor）","type":"server_error"}}

(The message reads "group xxx has no available channel (distributor) for model yyy".)

Specify a valid group explicitly when creating a key — do not rely on the default group.

List the account's available groups

GET /api/user/self/groups

The response is grouped by vendor; each group carries a description and a billing multiplier ratio (lower is cheaper):

{
  "data": {
    "claude": {
      "cl-cc-pro": {"desc": "...", "desc_en": "...", "ratio": 0.17},
      "cl-of-pro": {"desc": "...", "desc_en": "...", "ratio": 0.8}
    },
    "gemini": { "gm-of-pro": {"desc": "...", "ratio": 0.68} }
  },
  "message": "",
  "success": true
}

Put the group name (e.g. cl-cc-pro) into the key's group field.

⚠️ Group changes take effect with a delay

After changing a key's group via PUT /api/token/, or right after creating a key, the gateway holds a token cache, so the group change takes a few seconds (up to ~15s observed) to take effect on the model-call side. During this window:

Model calls still route through the old group;

You may briefly see "group X has no available channel" (where X is the old group).

This is a normal cache-refresh process, not a misconfiguration. Wait about 15 seconds after changing the group before verifying, or add a retry on the first call.

Troubleshooting model_not_found

Symptom	Cause	Action
`group X has no available channel for model Y`	Group X has no channel bound for model Y	Switch to a group that carries the model; confirm with `GET /api/user/self/groups`
Still reports the old group has no channel right after a group change	Token cache not yet refreshed	Wait ~15s and retry
A discounted group intermittently has no channel	Limited concurrency/stability of the discounted pool	Use a stable group, or retry later

Encoding Requirements

Request bodies must be UTF-8 encoded JSON. If a key name contains non-ASCII characters (e.g., Chinese):

On Windows, embedding non-ASCII text inline in a curl command may corrupt the name due to the local code page;

Use curl --data @file (file saved as UTF-8) or an HTTP client library in your programming language instead;

For automation scripts, ASCII-only key names are recommended — they avoid encoding issues and are easier to search by name.

1. Create a Key

Creates a new API key. The initial quota, expiration, and group can be specified at creation time.

Endpoint

POST /api/token/

Request Body

Parameter	Type	Required	Description
`name`	String	Yes	Key name, up to 50 characters
`remain_quota`	Integer	Yes	Initial quota (internal quota units), ≥ 0
`unlimited_quota`	Boolean	Yes	Unlimited quota flag; when `true`, `remain_quota` is ignored
`expired_time`	Integer	Yes	Expiration time (Unix timestamp in seconds); `-1` means never expires
`group`	String	No	Group; empty string uses the account's default group. The default group may have no available channel — specify a valid group explicitly; see "Groups"
`model_limits_enabled`	Boolean	No	Whether the model allowlist is enabled
`model_limits`	String	No	Model allowlist, comma-separated
`allow_ips`	String	No	IP allowlist; empty means unrestricted

Request Example

Response Example

{"message": "", "success": true}

The create endpoint does not return the key material directly. Call "List Keys" or "Search Keys" afterwards to obtain the new key's id and key.

2. List Keys

Endpoint

GET /api/token/?p=1&size=20

Parameter	Description
`p`	Page number, starting from 1
`size`	Items per page

Request Example

Response Example (excerpt)

{
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 3,
    "items": [
      {
        "id": 31333,
        "user_id": 669,
        "key": "PqXk****************************",
        "status": 1,
        "name": "prod-key-01",
        "created_time": 1784712786,
        "accessed_time": 1784712786,
        "expired_time": -1,
        "remain_quota": 5000000,
        "unlimited_quota": false,
        "used_quota": 0,
        "group": ""
      }
    ]
  },
  "message": "",
  "success": true
}

Key Response Fields

Field	Type	Description
`id`	Integer	Key ID; used for update/delete operations
`key`	String	Key material (prepend `sk-` when calling model APIs)
`status`	Integer	Status: `1` enabled, `2` disabled, `3` expired, `4` exhausted
`remain_quota`	Integer	Remaining quota (internal quota units)
`used_quota`	Integer	Cumulative consumed quota
`unlimited_quota`	Boolean	Unlimited quota flag
`expired_time`	Integer	Expiration timestamp; `-1` means never expires

3. Get a Single Key / Search by Name

GET /api/token/{id}
GET /api/token/search?keyword=<name_keyword>

Request Example

Response fields are identical to "List Keys".

4. Adjust Key Quota (Update a Key)

Endpoint

PUT /api/token/

⚠️ Important: This is a full-overwrite update
The request body must include all writable fields of the key — the record is overwritten as a whole. If you send only id and remain_quota, the key name will be cleared and the expiration time will be set to 0 (immediately expired).
Standard procedure: GET /api/token/{id} to fetch all current fields → modify only the target fields → write the whole object back.

Request Body

Parameter	Type	Required	Description
`id`	Integer	Yes	Key ID
`name`	String	Yes	Key name (fill in current value)
`remain_quota`	Integer	Yes	Target remaining quota (absolute value, not a delta)
`unlimited_quota`	Boolean	Yes	Unlimited quota flag
`expired_time`	Integer	Yes	Expiration timestamp (fill in current value)
`status`	Integer	Yes	Status (fill in current value)
`group`	String	Yes	Group (fill in current value)
`model_limits_enabled`	Boolean	Yes	Fill in current value
`model_limits`	String	Yes	Fill in current value
`allow_ips`	String	Yes	Fill in current value

Request Example (set quota to $0.5)

Response Example

{
  "data": { "id": 31333, "remain_quota": 250000, "...": "..." },
  "message": "",
  "success": true
}

After a successful update, the remaining quota shown on the console's "Token Management" page is updated in real time.

Validation Rules

When unlimited_quota is false, remain_quota must be non-negative and must not exceed the system maximum

remain_quota is a target value: to top up a key, compute current value + increment yourself and send the result

An expired or exhausted key cannot be re-enabled directly; fix expired_time / remain_quota first

5. Enable / Disable Only

To toggle the status without touching other fields, use the status_only parameter — no need to fill in all fields:

status: 1 enabled, 2 disabled.

6. Delete a Key

Endpoint

DELETE /api/token/{id}

Request Example

Response Example

{"message": "", "success": true}

Deletion takes effect immediately and cannot be undone. Proceed with caution.

Error Codes

Scenario	Response	Suggested Action
Token missing/invalid/mismatched with user ID	`{"code":401,"msg":"..."}`	Verify the system access token and `apex-api-user` belong to the same account
Key not found or not owned by this account	`{"success":false,"message":"record not found"}`	Check the key `id`
Negative quota / exceeds maximum	`{"success":false,"message":"..."}`	Fix `remain_quota`
Name too long	`{"success":false,"message":"..."}`	Name must be ≤ 50 characters

FAQ

Q: Does adjusting a key's quota affect the account balance?
A: No. Key quota and account balance are two independent layers. Consumption deducts from both simultaneously. The sum of all key quotas may exceed the account balance; actual availability is limited by whichever runs out first.

Q: Can I manage another account's keys through these APIs?
A: No. All endpoints operate only on keys owned by the account identified by apex-api-user.

Q: Can the quota be decreased?
A: Yes. remain_quota is a target value; both increases and decreases take effect immediately.

Q: Are API changes visible in the console?
A: Yes, in real time. Keys created and quotas adjusted through the API are immediately reflected on the console's "Token Management" page.

Q: A call returns "no available channel" right after creating a key or changing its group — what should I do?
A: The gateway's token cache has a few-seconds (up to ~15s) refresh delay, during which routing still follows the old group — this is expected; wait and retry. If it persists, the target group has no channel bound for that model; confirm with GET /api/user/self/groups and switch to a valid group. See "Groups".

Changelog

Version	Date	Notes
v1.0	2026-07-22	Initial release: create, query, quota adjustment, enable/disable, delete — full lifecycle verified in production

API Key Management API

DataEyes AI — API Key Management API#

Overview#

Base URLs#

Authentication#

Quota Units#

Groups#

The default group may have no available channel#

List the account's available groups#

⚠️ Group changes take effect with a delay#

Troubleshooting model_not_found#

Encoding Requirements#

1. Create a Key#

2. List Keys#

3. Get a Single Key / Search by Name#

4. Adjust Key Quota (Update a Key)#

⚠️ Important: This is a full-overwrite update#

5. Enable / Disable Only#

6. Delete a Key#

Error Codes#

FAQ#

Changelog#

DataEyes AI — API Key Management API

Overview

Base URLs

Authentication

Quota Units

Groups

The default group may have no available channel

List the account's available groups

⚠️ Group changes take effect with a delay

Troubleshooting model_not_found

Encoding Requirements

1. Create a Key

2. List Keys

3. Get a Single Key / Search by Name

4. Adjust Key Quota (Update a Key)

⚠️ Important: This is a full-overwrite update

5. Enable / Disable Only

6. Delete a Key

Error Codes

FAQ

Changelog