Search...
Menu

Obtain System Access Token & Authentication

Authentication

The AiLink open API uses system access token (PAT) authentication.

Authentication method

Include the following header in every request:

Header Required Notes
Authorization Yes Bearer <system-access-token>, generated in the console

Example request:

curl -sS "https://ailink.nativex.com/api/user/self" \
  -H "Authorization: Bearer <your-system-access-token>"

A missing header or an invalid token returns 401.


Getting credentials

System access token

A system access token is the credential for calling management APIs (the APIs described in this document).

How to get one:

Log in to the AiLink console → "Security & Access" → "Access Token" → click Create and copy the token.

It is a random string, as illustrated below:

abcd1234efgh5678ijkl9012mnop3456

Security tips:

•Keep it safe and treat it like a password.
•Do not hard-code it in front-end code or public repositories. Inject it into your server through environment variables or a secrets management system.
•If it leaks, regenerate it right away on the same page. The new token automatically revokes the old one.
•An account has only one valid access token at a time.
To find the user ID of your current account (for example, for troubleshooting or when contacting the support team), call GET /api/user/self with your system access token. data.id in the response body is the user ID.

How it differs from an API key (sk-xxx)

AiLink has two kinds of "tokens" with different purposes. Do not mix them up:

Name Purpose Header format
System access token Calls all management APIs in this document (create/query tokens, view logs, manage your account) Authorization: Bearer <token-value>
API key (token) Calls model APIs (business APIs such as /v1/chat/completions) Authorization: Bearer sk-xxx

The "Token Management (API Key)" chapter of this document covers creating, querying, and managing API keys, which is done with a system access token. You can think of it this way:

System access token  →  manages  →  API key  →  calls  →  model

Both use the Authorization: Bearer <value> format. The difference is that the identity behind each token value and the range of APIs it can call are different.


Verify authentication

Once you have a token, verify it with the following command:

curl -sS "https://ailink.nativex.com/api/user/self" \
  -H "Authorization: Bearer <your-system-access-token>"

Example success response (common fields only; see the notes below for the full list):

The actual data object returns many more fields than those listed below, including third-party binding info (github_id/discord_id/oidc_id/wechat_id/telegram_id/linux_do_id), display_name, setting, and others, mainly for display in the console front end. For typical integrations, you only need id, username, quota, used_quota, group, and status.
{
  "success": true,
  "message": "",
  "data": {
    "id": 12345,
    "username": "example_user",
    "role": 1,
    "status": 1,
    "email": "user@example.com",
    "group": "default",
    "quota": 5000000,
    "used_quota": 10000000,
    "request_count": 128,
    "permissions": { }
  }
}

Seeing success: true means authentication works and you can call all other APIs.


Common errors and troubleshooting

The following errors all return HTTP 401:

Scenario Cause Action
No Authorization provided The header is missing Add the header
Token is invalid or has been replaced by a new token The token is empty or wrong, or has been regenerated in the console Regenerate the access token in the console and use the latest value
Account banned Abnormal account status Contact support

Other related HTTP statuses:

Status code Scenario Action
403 Blocked at the permission level Check whether you are calling an API that your token does not have permission to access
429 Rate limit triggered Retry with exponential backoff

FAQ

Q: Can I call the management APIs in this document with an API key (sk-xxx)?
A: No. An API key can only call model APIs (/v1/*, /chat/*, etc.). Management APIs accept only a system access token.

Q: Does the access token expire?
A: No. It does not expire automatically. It stays valid until you regenerate it in the console (the old token is invalidated immediately).

Q: How many access tokens can one account have?
A: Only 1 valid token at a time. Each regeneration overwrites the old one. If you need to isolate environments (production / testing), use a different AiLink account for each environment.

Last modified: 2026-11-17