Search...
Menu

Token Management (API Key)

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:

•Token status codes: 1=Enabled, 2=Disabled, 3=Expired, 4=Exhausted.

1. Get token list

List all tokens under your account with pagination.

Request

•Method: GET
•Path: /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

•Method: GET
•Path: /api/token/search

Query 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

•The search API has its own rate limit. Calling it too frequently in a short time returns 429.
# 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

•Method: GET
•Path: /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

•Method: POST
•Path: /api/token/
•Content-Type: application/json

Body 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:

1
Call "Get token list" GET /api/token/ and find the id of the new token
2
Call 8. Get a single token (plaintext) to get the plaintext key

Example

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
•Create operations have their own rate limit.
•When 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

•Method: PUT
•Path: /api/token/
•Content-Type: application/json

Query 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

•Method: DELETE
•Path: /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 (used_quota) is not refunded when a token is deleted.
•Existing call logs remain in the history.
{
  "success": true,
  "message": ""
}

Example

Notes


7. Batch delete tokens

Delete multiple tokens at once.

Request

•Method: POST
•Path: /api/token/batch
•Content-Type: application/json

Body:

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

•Method: POST
•Path: /api/token/{id}/key

Path 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:

•Call it only when necessary. Ideally, after creating a token, fetch the plaintext key once and store it securely in your secrets management system, then let your application read it from there.
•This API must not be cached (the server forces no-cache headers).
•When rate limited, it returns 429. Wait a while before retrying.
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

•Method: POST
•Path: /api/token/batch/keys
•Content-Type: application/json

Body 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
•This API must not be cached (the server forces no-cache headers).
•When rate limited, it returns 429. Wait a while before retrying.
{
  "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

•Method: GET
•Path: /api/token/auto-groups

Response

{
  "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>"
Last modified: 2026-11-17