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:
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):
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.