II. Token Management (API Key)
In this chapter, a "token" is the API key you use to call model APIs (such as /v1/chat/completions). It looks like sk-xxxx and is different from the system access token.
General rules:
1=Enabled, 2=Disabled, 3=Expired, 4=Exhausted.1. Get token list
List all tokens under your account with pagination.
Request
GET/api/token/Query parameters (pagination optional):
| Parameter | Type | Default | Notes |
|---|---|---|---|
p |
int | 1 | Page number (starting from 1) |
page_size |
int | 10 | Items per page, max 100 |
Response
{
"success": true,
"message": "",
"data": {
"page": 1,
"page_size": 20,
"total": 3,
"items": [
{
"id": 1001,
"user_id": 12345,
"key": "Xyz8**********DefG",
"status": 1,
"name": "my-key",
"created_time": 1785225000,
"accessed_time": 1785225000,
"expired_time": -1,
"remain_quota": 500000,
"unlimited_quota": false,
"model_limits_enabled": false,
"model_limits": "",
"allow_ips": "",
"used_quota": 0,
"group": "",
"cross_group_retry": false,
"DeletedAt": null,
"auto_groups": null
}
]
}
}
Token object fields:
| Field | Type | Notes |
|---|---|---|
id |
int | Token ID |
user_id |
int | Owner user ID |
key |
string | The plaintext key is masked (first 4 characters + asterisks + last 4 characters). To view the plaintext key, see 8. Get a single token (plaintext) |
status |
int | Token status |
name |
string | Token name |
created_time |
int | Creation time (Unix timestamp in seconds) |
accessed_time |
int | Last used time |
expired_time |
int | Expiration time; -1 means never expires |
remain_quota |
int | Remaining quota (in quota units) |
unlimited_quota |
boolean | Whether quota is unlimited; when true, remain_quota is ignored |
used_quota |
int | Total used quota |
model_limits_enabled |
boolean | Whether the "allowed models only" restriction is enabled |
model_limits |
string | Allowed model names, comma-separated |
allow_ips |
string | IP allowlist, newline-separated; empty means no restriction |
group |
string | Group; empty means inheriting the account's default group |
cross_group_retry |
boolean | Cross-group retry (only takes effect for the auto group) |
auto_groups |
string[] / null | Auto group list; null if not set |
DeletedAt |
null | Soft-delete timestamp field currently returned by this API; it is null when a token is returned normally. Clients should not rely on this field |
Example
curl -sS "https://ailink.nativex.com/api/token/?p=1&page_size=20" \
-H "Authorization: Bearer <your-system-access-token>"
2. Search tokens
Search your tokens by name or by plaintext API key.
Request
GET/api/token/searchQuery parameters (provide at least one search condition):
| Parameter | Type | Notes |
|---|---|---|
keyword |
string | Fuzzy search by token name |
token |
string | Exact match by API key plaintext (the sk- prefix is stripped automatically) |
p |
int | Page number |
page_size |
int | Items per page |
Response
Same structure as "Get token list".
Example
# Search by name
curl -sS "https://ailink.nativex.com/api/token/search?keyword=production" \
-H "Authorization: Bearer <your-system-access-token>"
# Search by plaintext key
curl -sS "https://ailink.nativex.com/api/token/search?token=Xyz8AbcDefGhiJklMnoPqrStuVwxYz0123456789AbcDefG" \
-H "Authorization: Bearer <your-system-access-token>"
Notes
3. Get a single token
Get token details by ID (the plaintext key is still masked; to get it, see 8).
Request
GET/api/token/{id}Path parameters:
| Parameter | Type | Notes |
|---|---|---|
id |
int | Token ID |
Response
{
"success": true,
"message": "",
"data": {
"id": 1001,
"user_id": 12345,
"key": "Xyz8**********DefG",
"status": 1,
"name": "my-key",
"created_time": 1785225000,
"accessed_time": 1785225000,
"expired_time": -1,
"remain_quota": 500000,
"unlimited_quota": false,
"model_limits_enabled": false,
"model_limits": "",
"allow_ips": "",
"used_quota": 0,
"group": "",
"cross_group_retry": false,
"DeletedAt": null,
"auto_groups": null
}
}
Field meanings are the same as each item in "Get token list".
Common errors
| message | Resolution |
|---|---|
Token does not exist |
id is invalid or does not belong to the current account |
4. Create a token
Create a new API key.
Request
POST/api/token/application/jsonBody fields:
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
name |
string | Yes | — | Token name, ≤ 50 characters |
expired_time |
int | No | -1 |
Expiration timestamp (seconds); -1 means never expires |
remain_quota |
int | Conditional | 0 |
Quota (in quota units). Required and ≥ 0 when unlimited_quota=false |
unlimited_quota |
boolean | No | false |
Whether quota is unlimited |
model_limits_enabled |
boolean | No | false |
Whether to enable model restrictions |
model_limits |
string | No | "" |
Models allowed to be called, comma-separated (takes effect when model_limits_enabled=true) |
allow_ips |
string | No | "" |
IP allowlist, newline-separated; empty means no restriction |
group |
string | No | "" |
Group; empty means inheriting the account's default group |
cross_group_retry |
boolean | No | false |
Cross-group retry (only takes effect for the auto group) |
auto_groups |
string[] | No | — | Auto group list; omit this field to leave it unset, and pass an empty array to clear any auto groups already set |
Response
{
"success": true,
"message": ""
}
The response does not include the plaintext API key. To get the plaintext key:
GET /api/token/ and find the id of the new tokenExample
| message | Resolution |
|---|---|
Token name too long |
Truncate the name to 50 characters or fewer |
Maximum token limit reached (N) |
Delete unused tokens, or contact support to raise the limit |
Token quota cannot be negative |
A negative value was passed for remain_quota |
Token quota exceeds the maximum |
The quota of a single token is too large |
unlimited_quota=true, the token itself has no quota limit but is still bound by the account's total balance. Once the balance is exhausted, calls with every token fail.curl -sS -X POST "https://ailink.nativex.com/api/token/" \
-H "Authorization: Bearer <your-system-access-token>" \
-H "Content-Type: application/json" \
-d '{
"name": "Production - Main Key",
"remain_quota": 500000,
"unlimited_quota": false,
"expired_time": -1,
"model_limits_enabled": false,
"model_limits": "",
"allow_ips": "",
"group": "",
"cross_group_retry": false
}'
Common errors
Notes
5. Update a token
Update token properties; you can also update only the status.
Request
PUT/api/token/application/jsonQuery parameters:
| Parameter | Type | Notes |
|---|---|---|
status_only |
string | When non-empty, only the status field is updated and all other fields are ignored. Use it to quickly enable or disable a token |
Body fields:
| Field | Type | Required | Notes |
|---|---|---|---|
id |
int | Yes | Target token ID |
status |
int | Conditional | Token status: 1=Enabled, 2=Disabled, 3=Expired, 4=Exhausted (required in status_only mode) |
name |
string | No | Name (≤ 50 characters) |
expired_time |
int | No | Expiration timestamp |
remain_quota |
int | No | Remaining quota |
unlimited_quota |
boolean | No | Whether quota is unlimited |
model_limits_enabled |
boolean | No | Whether to enable model restrictions |
model_limits |
string | No | Allowed models (comma-separated) |
allow_ips |
string | No | IP allowlist |
group |
string | No | Group |
cross_group_retry |
boolean | No | Cross-group retry |
auto_groups |
string[] | No | Auto group list; omit this field to leave it unchanged, and pass an empty array to clear any auto groups already set |
Response
{
"success": true,
"message": "",
"data": {
"id": 1001,
"status": 1,
"name": "my-key",
"...": "..."
}
}
The structure of data is the same as "Get a single token".
Example
Enable or disable only:
# Enable
curl -sS -X PUT "https://ailink.nativex.com/api/token/?status_only=1" \
-H "Authorization: Bearer <your-system-access-token>" \
-H "Content-Type: application/json" \
-d '{"id": 1001, "status": 1}'
# Disable
curl -sS -X PUT "https://ailink.nativex.com/api/token/?status_only=1" \
-H "Authorization: Bearer <your-system-access-token>" \
-H "Content-Type: application/json" \
-d '{"id": 1001, "status": 2}'
Full update (change name, quota, and group):
| message | Resolution |
|---|---|
Token does not exist |
id is invalid or does not belong to the current account |
Expired tokens cannot be enabled |
Update expired_time first |
Exhausted tokens cannot be enabled |
Adjust remain_quota first, or set the token to unlimited quota |
curl -sS -X PUT "https://ailink.nativex.com/api/token/" \
-H "Authorization: Bearer <your-system-access-token>" \
-H "Content-Type: application/json" \
-d '{
"id": 1001,
"status": 1,
"name": "Production - Main Key",
"remain_quota": 1000000,
"unlimited_quota": false,
"expired_time": -1,
"group": ""
}'
Common errors
6. Delete a token
Permanently delete a token by ID. After deletion, calls to model APIs with this token fail immediately.
Request
DELETE/api/token/{id}Path parameters:
| Parameter | Type | Notes |
|---|---|---|
id |
int | Token ID |
Response
curl -sS -X DELETE "https://ailink.nativex.com/api/token/1001" \
-H "Authorization: Bearer <your-system-access-token>"
used_quota) is not refunded when a token is deleted.{
"success": true,
"message": ""
}
Example
Notes
7. Batch delete tokens
Delete multiple tokens at once.
Request
POST/api/token/batchapplication/jsonBody:
| Field | Type | Required | Notes |
|---|---|---|---|
ids |
int[] | Yes | Array of token IDs to delete, non-empty |
Response
| Field | Notes |
|---|---|
data |
Number of tokens actually deleted (IDs that don't belong to the current account or were already deleted are skipped) |
curl -sS -X POST "https://ailink.nativex.com/api/token/batch" \
-H "Authorization: Bearer <your-system-access-token>" \
-H "Content-Type: application/json" \
-d '{"ids": [1001, 1002, 1003]}'
| message | Resolution |
|---|---|
Invalid parameter |
ids is empty or malformed |
{
"success": true,
"message": "",
"data": 3
}
Example
Common errors
8. Get a single token (plaintext)
Get the plaintext API key of a specified token so you can configure it in your application. This API is strictly rate limited.
Request
POST/api/token/{id}/keyPath parameters:
| Parameter | Type | Notes |
|---|---|---|
id |
int | Token ID |
No request body.
Response
| Field | Notes |
|---|---|
data.key |
Plaintext key, used to call model APIs with Authorization: Bearer <key> |
curl -sS -X POST "https://ailink.nativex.com/api/token/1001/key" \
-H "Authorization: Bearer <your-system-access-token>"
{
"success": true,
"message": "",
"data": {
"key": "Xyz8AbcDefGhiJklMnoPqrStuVwxYz0123456789AbcDefG"
}
}
Example
After getting the plaintext key, call a model:
| HTTP | message | Resolution |
|---|---|---|
| 200 | Token does not exist |
id is invalid or does not belong to the current account |
| 429 | — | Too many requests in a short time. Wait a moment and try again |
curl -sS -X POST "https://ailink.nativex.com/v1/chat/completions" \
-H "Authorization: Bearer Xyz8AbcDefGhiJklMnoPqrStuVwxYz0123456789AbcDefG" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role":"user","content":"ping"}]
}'
Notes
Common errors
9. Batch get token plaintext keys
Get the plaintext API keys of multiple tokens at once. It is also strictly rate limited, and its purpose and restrictions are the same as "Get a single token (plaintext)".
Request
POST/api/token/batch/keysapplication/jsonBody fields:
| Field | Type | Required | Notes |
|---|---|---|---|
ids |
int[] | Yes | Array of token IDs to query, non-empty, up to 100 per request |
Response
| Field | Notes |
|---|---|
data.keys |
A map with the token ID (as a string) as key and the plaintext API key as value. IDs that don't belong to the current account are silently skipped and do not appear in the result |
curl -sS -X POST "https://ailink.nativex.com/api/token/batch/keys" \
-H "Authorization: Bearer <your-system-access-token>" \
-H "Content-Type: application/json" \
-d '{"ids": [1001, 1002]}'
| message | Resolution |
|---|---|
Invalid parameter |
ids is empty or missing |
Batch operation count cannot exceed 100 |
A single ids array contains more than 100 items; query in batches |
{
"success": true,
"message": "",
"data": {
"keys": {
"1001": "Xyz8AbcDefGhiJklMnoPqrStuVwxYz0123456789AbcDefG",
"1002": "Abc1DefGhiJklMnoPqrStuVwxYz0123456789AbcDefGhij"
}
}
}
Example
Common errors
Notes
10. Get available auto groups
Get the list of auto groups the current account can choose from, and the maximum number of groups you can configure.
Request
GET/api/token/auto-groupsResponse
{
"success": true,
"message": "",
"data": {
"groups": [
"default",
"vip"
],
"max_count": 5
}
}
| Field | Type | Notes |
|---|---|---|
data.groups |
string[] | Names of the auto groups the current account can choose from |
data.max_count |
int | Maximum number of auto groups configurable per token |
Example
curl -sS "https://ailink.nativex.com/api/token/auto-groups" \
-H "Authorization: Bearer <your-system-access-token>"