Token Management API

API Overview

The Token Management API lets you handle the full lifecycle of your API keys in code, instead of clicking through the console one key at a time. The most common use case is batch issuance: giving each team member, downstream customer, or project its own key, each with its own limits on how much it can spend, which models it can call, and how long it stays valid. Combined with a scheduled job, you can also give each key a daily budget that resets automatically.

Quota limit

remain_quota caps how much this key can spend in total

Model limit

models sets an allowlist; calls to anything outside it are rejected

Expiry limit

expired_time sets an expiry timestamp, after which the key stops working

If you only need one or two keys, the console is faster — see How to create an API key. This API is aimed at automated issuance, scheduled rotation, or integrating key management into your own systems.

How to Get a Personal Access Token

The Token Management API authenticates with a personal access token (starting with nap_), which is not the same thing as an API key.

Open Personal Access Tokens

Go to your profile page at api.apiyi.com/account/profile. Under Account Options, click Personal Access Tokens → Create Token.

Select the Model keys permissions you need

The three permissions are independent. Select only the ones you use:

What you want to do	Permission to select
List or get API keys	Model keys · Read
Create, update, disable or delete API keys	Model keys · Write
Retrieve a new API key’s plaintext (to hand it out)	Model keys · Reveal secret

A bulk-issuance script needs all three. A usage-monitoring script only needs Read.

Set the expiry and IP allowlist

The default expiry is 30 days, so we recommend a longer period. If your issuance script runs on a server with a fixed IP, we strongly recommend an IP allowlist. The allowlist can’t be edited after creation, so get the script working without one first, then create a separate production token with an allowlist.

Create a personal access token: name, expiry, IP allowlist and permissions

A token with Write and Reveal secret can create API keys that call models. Treat it like your account password.A personal access token cannot call models itself, but it can issue keys that can. Give this kind of token an IP allowlist, store it in a secret manager rather than in code, never commit it to a repository, and replace it before it expires.

Legacy system tokens are scheduled to retire on 2026-11-11 (UTC+8). AccessTokens generated under “Account Options - System Token” keep working until then. After that date they return 401 ACCESS_TOKEN_LEGACY_RETIRED. We will review usage and may extend the date, but we recommend switching to a personal access token now. When you switch, also check your scripts: the create endpoint now returns a masked key. To get the plaintext, call POST /api/token/{id}/key as described below. See What Is a Personal Access Token?

Endpoints

All endpoints authenticate the same way: put the personal access token in the Authorization header. The Bearer prefix is optional.

Method	Path	Purpose	Permission
`GET`	`/api/token/?p=0&page_size=100`	List all tokens on your account (`key` is masked)	Read
`GET`	`/api/token/{id}`	Retrieve a single token	Read
`POST`	`/api/token/`	Create a token (`key` in the response is masked)	Write
`POST`	`/api/token/{id}/key`	Retrieve the key’s plaintext	Reveal secret
`PUT`	`/api/token/`	Update a token (requires the complete object)	Write
`PUT`	`/api/token/?status_only=true`	Toggle enabled/disabled state only	Write
`DELETE`	`/api/token/{id}`	Delete a token	Write

The base URL is https://api.apiyi.com.

Creating a Token

Request Example

export APIYI_SYS_TOKEN='nap_YOUR_PERSONAL_ACCESS_TOKEN'   # personal access token

curl --compressed -s -X POST 'https://api.apiyi.com/api/token/' \
  -H "Authorization: $APIYI_SYS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "team-alice",
    "remain_quota": 500000,
    "unlimited_quota": false,
    "group": "default",
    "models": "gpt-5.6,deepseek-chat",
    "expired_time": -1
  }'

Request Fields

Field	Type	Description
`name`	String	Token name, for your own identification
`remain_quota`	Integer	Quota cap in credits; 500,000 = $1.00
`unlimited_quota`	Boolean	Whether quota is unlimited; defaults to `false`
`group`	String	The group identifier the token is bound to, e.g. `default`
`models`	String	Model allowlist, comma-separated; omit for no restriction
`expired_time`	Integer	Expiry timestamp in Unix seconds; `-1` means never expires

unlimited_quota defaults to false and remain_quota defaults to 0 — omitting both produces a token with zero quota that cannot be used. Either set remain_quota explicitly or set unlimited_quota to true.

Use the models field for the model allowlist.The response structure also contains model_limits, model_limits_enabled, and allow_ips. Passing these does not raise an error — the endpoint still returns 200 — but they currently have no effect, and reading the token back shows them unset. Use models to restrict available models. Source-IP restrictions need to be implemented on your own side for now.

Response Example

{
  "success": true,
  "message": "",
  "data": {
    "id": 119431,
    "user_id": 80778,
    "key": "K1RP**********4b75",
    "status": 1,
    "name": "team-alice",
    "group": "default",
    "models": "gpt-5.6,deepseek-chat",
    "remain_quota": 500000,
    "unlimited_quota": false,
    "used_quota": 0,
    "expired_time": -1,
    "created_time": 1785599000
  }
}

The key in the response is masked and can’t be used directly. To get the plaintext, call the retrieve-plaintext endpoint with the id from the response.

Retrieve the Key Plaintext

curl --compressed -s -X POST 'https://api.apiyi.com/api/token/119431/key' \
  -H "Authorization: $APIYI_SYS_TOKEN"

{
  "success": true,
  "message": "",
  "data": {
    "key": "K1RPzapuXLfBU4kDC5D9C0E70b1841AeAa542186B2F54b75"
  }
}

The personal access token needs Model keys · Reveal secret, otherwise you get 403 ACCESS_TOKEN_SCOPE_DENIED.
The returned key does not include the sk- prefix. Prepend it yourself. In the example above, the actual API key is sk-K1RPzapu….
Save it right away and distribute it over a secure channel. Don’t leave the response body in log files.

Batch Creation

There is no server-side batch endpoint — passing something like count in the request body has no effect and still creates a single token. Batch issuance is done by looping on the client.

A single user can hold at most 1,000 tokens. This is an account-wide cap and it counts tokens that are disabled but not deleted. Once you hit it, the create endpoint fails — delete tokens you no longer use to free up slots.Before a batch run, page through GET /api/token/?p=0&page_size=100 to count what you already have. When rotating keys, actually finish the last step of “create new key → shift traffic → disable old key → delete once no calls remain”. Disabling without deleting keeps the slot occupied, so a few rotation cycles will run you into the cap.

Python
Node.js
cURL

import json
import os
import time

import requests

BASE = "https://api.apiyi.com"
HEADERS = {"Authorization": os.environ["APIYI_SYS_TOKEN"],
           "Content-Type": "application/json"}
QUOTA_PER_USD = 500_000


def create_token(name, quota_usd=None, group="default", models=None, days=0):
    """Create one token. quota_usd=None means unlimited; days=0 means never expires."""
    body = {
        "name": name,
        "group": group,
        "unlimited_quota": quota_usd is None,
        "remain_quota": 0 if quota_usd is None else int(quota_usd * QUOTA_PER_USD),
        "expired_time": -1 if not days else int(time.time()) + days * 86400,
    }
    if models:
        body["models"] = models

    resp = requests.post(f"{BASE}/api/token/", headers=HEADERS, json=body, timeout=30)
    resp.raise_for_status()
    data = resp.json()["data"]          # key here is masked

    # Retrieve the plaintext: needs "Model keys · Reveal secret"
    resp = requests.post(f"{BASE}/api/token/{data['id']}/key", headers=HEADERS, timeout=30)
    resp.raise_for_status()
    key = resp.json()["data"]["key"]
    return {"id": data["id"], "name": data["name"], "key": "sk-" + key}


if __name__ == "__main__":
    names = ["team-alice", "team-bob", "team-carol"]
    created = [
        create_token(n, quota_usd=1, group="default", models="gpt-5.6", days=30)
        for n in names
    ]
    for row in created:
        print(f"{row['name']:16s} id={row['id']} {row['key']}")

    # keys.json holds plaintext keys: store and distribute carefully, delete when done
    with open("keys.json", "w") as f:
        json.dump(created, f, ensure_ascii=False, indent=1)

const BASE = "https://api.apiyi.com";
const HEADERS = {
  Authorization: process.env.APIYI_SYS_TOKEN,
  "Content-Type": "application/json",
};
const QUOTA_PER_USD = 500_000;

async function createToken(name, { quotaUsd = null, group = "default",
                                   models = null, days = 0 } = {}) {
  const body = {
    name,
    group,
    unlimited_quota: quotaUsd === null,
    remain_quota: quotaUsd === null ? 0 : Math.round(quotaUsd * QUOTA_PER_USD),
    expired_time: days ? Math.floor(Date.now() / 1000) + days * 86400 : -1,
  };
  if (models) body.models = models;

  const resp = await fetch(`${BASE}/api/token/`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify(body),
  });
  if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
  const { data } = await resp.json();   // key here is masked

  // Retrieve the plaintext: needs "Model keys · Reveal secret"
  const r2 = await fetch(`${BASE}/api/token/${data.id}/key`, { method: "POST", headers: HEADERS });
  if (!r2.ok) throw new Error(`HTTP ${r2.status}`);
  const { data: secret } = await r2.json();
  return { id: data.id, name: data.name, key: `sk-${secret.key}` };
}

const names = ["team-alice", "team-bob", "team-carol"];
for (const name of names) {
  const row = await createToken(name, { quotaUsd: 1, models: "gpt-5.6", days: 30 });
  console.log(row.name, row.id, row.key);
}

export APIYI_SYS_TOKEN='nap_YOUR_PERSONAL_ACCESS_TOKEN'   # personal access token

for NAME in team-alice team-bob team-carol; do
  ID=$(curl --compressed -s -X POST 'https://api.apiyi.com/api/token/' \
    -H "Authorization: $APIYI_SYS_TOKEN" \
    -H 'Content-Type: application/json' \
    -d "{\"name\":\"$NAME\",\"remain_quota\":500000,\"unlimited_quota\":false,\"group\":\"default\",\"expired_time\":-1}" \
    | jq -r '.data.id')
  KEY=$(curl --compressed -s -X POST "https://api.apiyi.com/api/token/$ID/key" \
    -H "Authorization: $APIYI_SYS_TOKEN" | jq -r '.data.key')
  printf '%s\tsk-%s\n' "$NAME" "$KEY"
done

Using the Three Limits

Quota limit

remain_quota caps what the token can spend. The conversion matches the Balance Query API:

Conversion Rule

500,000 quota = $1.00 USD

For example, to issue a downstream customer a key capped at $10, set remain_quota to 5000000 with unlimited_quota set to false. Consumption so far is readable from the token’s used_quota field. remain_quota is a one-off total and does not refill on its own. For a daily budget, see Scenario: Daily Per-Key Limits That Reset Automatically below.

Model limit

models is a comma-separated allowlist. Once set, calling a model outside the list is rejected:

{
  "error": {
    "message": "This token is not authorized to use model: deepseek-chat"
  }
}

The response is HTTP 403 and no charge is incurred. Omitting models means no restriction.

Expiry limit

expired_time is a Unix-seconds timestamp, with -1 meaning never. For example, a key that expires in 30 days:

import time
expired_time = int(time.time()) + 30 * 86400

Listing Tokens

curl --compressed -s 'https://api.apiyi.com/api/token/?p=0&page_size=100' \
  -H "Authorization: $APIYI_SYS_TOKEN" | jq '.data[] | {id, name, status, remain_quota, used_quota, models}'

Key fields:

Field	Description
`id`	Token ID, used for updates and deletion
`key`	Masked key; see “Retrieve the Key Plaintext” for the plaintext
`status`	`1` = enabled, `2` = disabled
`remain_quota` / `used_quota`	Remaining / consumed quota
`unlimited_quota`	Whether quota is unlimited
`models`	Model allowlist; empty means no restriction
`expired_time`	Expiry timestamp; `-1` means never

Updating a Token

The update endpoint requires the complete object — it is not a patch.The correct flow is: GET the full token object, modify the fields you want to change, then PUT the whole object back. Sending only the changed fields will clear the rest.

import os
import requests

BASE = "https://api.apiyi.com"
HEADERS = {"Authorization": os.environ["APIYI_SYS_TOKEN"],
           "Content-Type": "application/json"}

# 1. fetch the complete object
token = requests.get(f"{BASE}/api/token/119431", headers=HEADERS, timeout=30).json()["data"]

# 2. change only what you need, leaving everything else as-is
token["remain_quota"] = 2_500_000     # raise the cap to $5
token["models"] = "gpt-5.6,gemini-3-pro"

# 3. PUT the whole object back
resp = requests.put(f"{BASE}/api/token/", headers=HEADERS, json=token, timeout=30)
print(resp.json()["success"])

Scenario: Daily Per-Key Limits That Reset Automatically

When a company hands keys to workflows, team members, or downstream projects, a common requirement is “each key may spend at most $5 a day, and the limit comes back the next day”. If a workflow runs away, the damage is capped at one day’s budget. The platform has no built-in “daily quota” field yet, but the update endpoint above plus a scheduled job that runs once at midnight does the job: every day it sets remain_quota on those keys back to the daily cap. The keys themselves never change, so team members keep using the same key. Once a key’s budget is used up for the day, calls are rejected (and not charged); after the midnight reset they work again.

Prepare a personal access token

Grant Model keys · Read and Model keys · Write; Reveal secret is not needed. If the script runs on a server with a fixed IP, set an IP allowlist on the token.

List the keys to limit and their daily caps

Look up each key’s id with the listing endpoint and fill them into DAILY_BUDGET_USD in the script below.

Run the script once a day at 00:00 (UTC+8)

cron, a cloud-function timer, or any scheduler will do — see below.

Reset script

"""Run once a day at 00:00 (UTC+8): reset the listed tokens' quota to the daily cap."""
import json
import os
from datetime import datetime, timedelta, timezone
from pathlib import Path

import requests

BASE = "https://api.apiyi.com"
HEADERS = {"Authorization": os.environ["APIYI_SYS_TOKEN"],
           "Content-Type": "application/json"}
QUOTA_PER_USD = 500_000

# token ID -> daily cap (USD)
DAILY_BUDGET_USD = {
    119431: 5,     # team-alice
    119432: 5,     # team-bob
    119433: 20,    # workflow-prod
}
CARRY_OVERDRAFT = True   # deduct yesterday's overspend from today's budget

TZ = timezone(timedelta(hours=8))   # a "day" is measured in UTC+8
STATE = Path(__file__).with_name("daily_quota_state.json")


def main():
    today = datetime.now(TZ).date().isoformat()
    state = json.loads(STATE.read_text()) if STATE.exists() else {}

    for token_id, usd in DAILY_BUDGET_USD.items():
        last = state.get(str(token_id), {})
        if last.get("date") == today:
            continue                     # already reset today; don't hand out a second day's budget

        # 1. fetch the complete object
        token = requests.get(f"{BASE}/api/token/{token_id}",
                             headers=HEADERS, timeout=30).json()["data"]
        remain = token["remain_quota"]
        if "quota" in last:
            spent = (last["quota"] - remain) / QUOTA_PER_USD
            print(f"{token['name']}: spent ${spent:.2f} last period")

        # 2. change only the quota fields, leaving everything else as-is
        quota = int(usd * QUOTA_PER_USD)
        if CARRY_OVERDRAFT and remain < 0:
            quota = max(quota + remain, 0)
        token["remain_quota"] = quota
        token["unlimited_quota"] = False

        # 3. PUT the whole object back
        resp = requests.put(f"{BASE}/api/token/", headers=HEADERS,
                            json=token, timeout=30).json()
        if not resp.get("success"):
            raise RuntimeError(f"failed to reset token {token_id}: {resp.get('message')}")

        # save after each token, so a rerun after a mid-way failure skips the ones already done
        state[str(token_id)] = {"date": today, "quota": quota}
        STATE.write_text(json.dumps(state, indent=1))
        print(f"{token['name']}: today's budget ${quota / QUOTA_PER_USD:.2f}")


if __name__ == "__main__":
    main()

The script does three extra things:

No double resets: if it fires twice in one day (a scheduler catch-up run, a manual rerun), it does not hand out another day’s budget
Carries overspend forward: the quota is a soft cap (see below), so whatever went over yesterday is deducted today, keeping the daily average within the cap over time. Set CARRY_OVERDRAFT to False if you don’t want this
Prints yesterday’s spend: each run logs how much every key spent in the previous period, so the log doubles as a simple daily report

Scheduling

Put the token in an environment file only you can read, then trigger the script daily with cron:

# /opt/apiyi-quota/env (chmod 600)
export APIYI_SYS_TOKEN='nap_YOUR_PERSONAL_ACCESS_TOKEN'

# crontab -e
# server time zone is UTC+8:
0 0 * * * . /opt/apiyi-quota/env && python3 /opt/apiyi-quota/reset_daily_quota.py >> /opt/apiyi-quota/reset.log 2>&1
# server time zone is UTC: 00:00 (UTC+8) = 16:00 (UTC), so start the line with 0 16 * * *

To define “a day” in another time zone, change both the cron time and TZ in the script.

Things to know before you rely on it

The quota is a soft cap, not a precise brake. The quota check happens when a request starts, so several concurrent requests can pass it at the same time, and a single expensive request (video, 4K images, very long context) can cross the cap in one go, pushing the balance negative. The higher the concurrency and unit price, the bigger the overshoot. The script’s overspend carry-forward deducts it the next day; if some keys must never overshoot, control their concurrency on your own side or use the models allowlist to exclude expensive models.

A reset overwrites, it doesn’t add: unused budget does not roll over to the next day. Any manual change you make to these keys’ quota in the console is also overwritten at the next reset
Requests in flight around midnight: a request sent before midnight that finishes after it may be billed against the new day — usually a small amount
If the script doesn’t run, keys stay exhausted: calls are temporarily blocked, but nothing extra is spent. Add failure alerts to the scheduled job
The account balance is still the master limit: if the keys’ daily caps add up to more than your account balance, the balance runs out first and every key stops
Need to give one key a bit more today? Raise that key’s remain_quota with the update endpoint; it resets back to the cap the next day as usual

Disabling and Deleting

Disable (keeps the record)

Once disabled, the key stops working immediately — calls with it return 401 — but the token record and its usage history are retained.

token = requests.get(f"{BASE}/api/token/119431", headers=HEADERS, timeout=30).json()["data"]
token["status"] = 2      # 1 = enabled, 2 = disabled

requests.put(f"{BASE}/api/token/", headers=HEADERS,
             params={"status_only": "true"}, json=token, timeout=30)

Delete (irreversible)

curl --compressed -s -X DELETE 'https://api.apiyi.com/api/token/119431' \
  -H "Authorization: $APIYI_SYS_TOKEN"

Batch deletion is likewise a client-side loop:

for token_id in [119431, 119432, 119433]:
    requests.delete(f"{BASE}/api/token/{token_id}", headers=HEADERS, timeout=30)

Deletion cannot be undone. If you only want to suspend a key temporarily, disable it instead — the usage history stays available for reconciliation.

FAQ

The key returned at creation does not work — why?

The create endpoint returns a masked key (with a run of * in the middle), so it can’t be used directly. Call POST /api/token/{id}/key with the returned id to get the plaintext (needs the Reveal secret permission), then prepend sk-. If an older script uses the key from the create response directly, add this step when you switch to a personal access token.

Why does my newly created token report insufficient quota?

Most likely neither remain_quota was set nor unlimited_quota was set to true at creation. That default combination produces a token with zero quota. Recreate it with one of the two specified explicitly.

Why do model_limits or allow_ips have no effect?

Those fields — along with model_limits_enabled — currently do not take effect. Passing them raises no error but nothing is stored. Use models to restrict available models; source-IP restrictions need to be handled on your own side for now.

Can I create several tokens in a single request?

There is no server-side batch endpoint, and passing something like count in the body has no effect. Loop the create call on the client instead — see the batch creation section above.

How many tokens can one account hold?

At most 1,000 per user, and tokens that are disabled but not deleted count toward that total. Once you reach the cap, creation fails until you delete tokens you no longer need. When rotating keys, remember to finish with the delete step — disabling alone keeps the slot taken.

Can I cap each key's daily spend and have it reset the next day?

There is no built-in daily quota field, but a scheduled job does it: at 00:00 (UTC+8) every day, call the update endpoint to set those keys’ remain_quota back to the daily cap. The keys don’t change; once a key’s budget is used up, calls are rejected and not charged, and it works again the next day. See Scenario: Daily Per-Key Limits That Reset Automatically above for the full script and caveats.

My other fields got cleared after an update

The update endpoint requires the complete object. GET the full object first, modify it, then PUT the whole thing back rather than sending only the changed fields.

What is the difference between disabling and deleting?

Disabling (status: 2) stops the key working immediately but keeps the record and usage history, and you can set it back to 1 at any time. Deleting is irreversible and removes the record. For temporary suspension, prefer disabling.

How do I see how much each key has spent?

The token’s used_quota field is that key’s cumulative spend (÷ 500,000 = USD). For a per-period breakdown or call-level detail, filter by token name on the console log page — see How to view my call records.

Important Notes

A personal access token is not an API key, and the two are not interchangeable

An API key (starting with sk-) is for /v1/* inference endpoints
A personal access token (starting with nap_) is for /api/* management endpoints and cannot call models

Error reference: 401 ACCESS_TOKEN_LEGACY_RETIRED means you are still using a retired legacy system token. 401 This access token may not be used from the current IP address. means the request came from an IP outside the token’s allowlist. 403 ACCESS_TOKEN_SCOPE_DENIED means the token lacks the permission this endpoint needs (see the Endpoints table).

Handle plaintext keys carefullyThe retrieve-plaintext endpoint returns a key that can call models directly. Therefore:

Do not write response bodies containing key into log files or commit them to a repository
Distribute keys to team members over secure channels, not group chats
This plaintext does not carry the sk- prefix, so common secret scanners may not detect it — do not rely on automated checks to catch it for you

Operational tips

When creating in bulk, add a modest delay between calls to avoid high instantaneous concurrency
Give each key a meaningful name (such as team-alice or prod-webhook) so you can attribute usage by token_name in the logs later
For rotation: create the new key, shift traffic, disable the old key, observe for a while, and only delete it once you confirm no calls remain

Basics

Basic API

Image API (Official)

Video API (Official)

Multimodal Understanding API

Text Generation

Audio API (Official)

Retrieval & Safety

API Overview

Quota limit

Model limit

Expiry limit

How to Get a Personal Access Token

Endpoints

Creating a Token

Request Example

Request Fields

Response Example

Retrieve the Key Plaintext

Batch Creation

Using the Three Limits

Quota limit

Conversion Rule

Model limit

Expiry limit

Listing Tokens

Updating a Token

Scenario: Daily Per-Key Limits That Reset Automatically

Reset script

Scheduling

Things to know before you rely on it

Disabling and Deleting

Disable (keeps the record)

Delete (irreversible)

FAQ

Important Notes

Related Documentation

​API Overview

Quota limit

Model limit

Expiry limit

​How to Get a Personal Access Token

​Endpoints

​Creating a Token

​Request Example

​Request Fields

​Response Example

​Retrieve the Key Plaintext

​Batch Creation

​Using the Three Limits

​Quota limit

Conversion Rule

​Model limit

​Expiry limit

​Listing Tokens

​Updating a Token

​Scenario: Daily Per-Key Limits That Reset Automatically

​Reset script

​Scheduling

​Things to know before you rely on it

​Disabling and Deleting

​Disable (keeps the record)

​Delete (irreversible)

​FAQ

​Important Notes

Related Documentation

API Overview

How to Get a Personal Access Token

Endpoints

Creating a Token

Request Example

Request Fields

Response Example

Retrieve the Key Plaintext

Batch Creation

Using the Three Limits

Quota limit

Model limit

Expiry limit

Listing Tokens

Updating a Token

Scenario: Daily Per-Key Limits That Reset Automatically

Reset script

Scheduling

Things to know before you rely on it

Disabling and Deleting

Disable (keeps the record)

Delete (irreversible)

FAQ

Important Notes