API Key Management

Overview

API keys are managed under /api/token. These endpoints use the system access token described in Authentication and quota.

PUT /api/token/ performs a full mutable-settings update, not a JSON Merge Patch. Include every setting that must be preserved.

Mutable fields

Field	Type	Description
`id`	integer	Required for updates
`name`	string	Display name, maximum 50 characters
`expired_time`	integer	Unix timestamp in seconds; `-1` means no expiration
`remain_quota`	integer	Remaining quota in internal units
`unlimited_quota`	boolean	Disables the key-level quota ceiling when `true`
`model_limits_enabled`	boolean	Enables the model allowlist
`model_limits`	string	Comma-separated model IDs
`allow_ips`	string or null	Newline-separated IP addresses or CIDR ranges; an empty string or `null` means unrestricted
`group`	string	Routing and billing group
`cross_group_retry`	boolean	Cross-group retry; only meaningful for supported automatic groups
`smart_routing`	boolean	Marks the record as a Smart Routing key
`smart_route_tiers`	string	JSON-encoded Smart Routing tier configuration

Create a standard API key

curl -fsS -X POST "$BASE_URL/api/token/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-deployment",
    "expired_time": -1,
    "remain_quota": 0,
    "unlimited_quota": true,
    "model_limits_enabled": false,
    "model_limits": "",
    "allow_ips": "",
    "group": "default",
    "cross_group_retry": false,
    "smart_routing": false,
    "smart_route_tiers": ""
  }' | jq

A successful create response does not include the record ID. Use a unique name, then locate the new record through list or search.

List and search

Standard-key lists exclude Smart Routing keys by default:

curl -fsS "$BASE_URL/api/token/?p=1&size=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" | jq

Set exclude_smart_routing=false to include every key:

curl -fsS "$BASE_URL/api/token/?p=1&size=20&exclude_smart_routing=false" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" | jq

Supported page-size parameter names are size, page_size, and ps. The maximum page size is 100. Search by name or stored key value:

curl -fsS --get "$BASE_URL/api/token/search" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  --data-urlencode "keyword=ci-deployment" \
  --data-urlencode "p=1" \
  --data-urlencode "size=20" | jq

The optional token query parameter accepts a key with or without the sk- prefix. List, search, and read responses always mask the key value.

Read and reveal

Read a masked record:

curl -fsS "$BASE_URL/api/token/42" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" | jq

Reveal the complete stored value:

stored_key=$(curl -fsS -X POST "$BASE_URL/api/token/42/key" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  | jq -er '.data.key')

api_key="sk-${stored_key#sk-}"

Reveal endpoints return the stored value without adding sk-. Treat the response as a secret and write it directly to a secrets manager rather than printing it. Reveal up to 100 keys in one request:

curl -fsS -X POST "$BASE_URL/api/token/batch/keys" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{"ids":[42,43]}'

Safely update a key

Read the current record, construct a complete mutable payload, and change only the intended values:

current=$(curl -fsS "$BASE_URL/api/token/42" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID")

payload=$(jq '.data | {
  id,
  name,
  expired_time,
  remain_quota,
  unlimited_quota,
  model_limits_enabled,
  model_limits,
  allow_ips,
  group,
  cross_group_retry,
  smart_routing,
  smart_route_tiers
} | .name = "ci-deployment-v2"' <<< "$current")

curl -fsS -X PUT "$BASE_URL/api/token/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d "$payload" | jq

This read-modify-write pattern preserves model limits and Smart Routing settings.

Enable or disable

Status-only updates preserve all other settings:

curl -fsS -X PUT "$BASE_URL/api/token/?status_only=true" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{"id":42,"status":2}' | jq

Status	Meaning
`1`	Enabled
`2`	Manually disabled
`3`	Expired
`4`	Quota exhausted

An expired or exhausted key cannot be enabled until its expiration or quota condition is corrected.

Delete keys

Delete one key:

curl -fsS -X DELETE "$BASE_URL/api/token/42" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" | jq

Delete multiple owned keys:

curl -fsS -X POST "$BASE_URL/api/token/batch" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{"ids":[42,43]}' | jq

The batch response data value is the number of records actually deleted.

Complete lifecycle script

This script creates a one-hour key with a USD-denominated ceiling, locates it, reveals it without logging the secret, updates it, disables it, and deletes it.

#!/usr/bin/env bash
set -euo pipefail

: "${BASE_URL:=https://api.mixroute.ai}"
: "${ACCESS_TOKEN:?Set ACCESS_TOKEN}"
: "${USER_ID:?Set USER_ID}"

auth=(
  -H "Authorization: Bearer $ACCESS_TOKEN"
  -H "New-Api-User: $USER_ID"
)

name="automation-$(date +%s)-$RANDOM"
token_id=""

delete_token() {
  local response
  response=$(curl -fsS -X DELETE "$BASE_URL/api/token/$token_id" \
    "${auth[@]}")
  jq -e '.success == true' <<< "$response" >/dev/null
}

cleanup() {
  if [[ -n "$token_id" ]]; then
    delete_token >/dev/null 2>&1 || true
  fi
}
trap cleanup EXIT

quota_per_unit=$(curl -fsS "$BASE_URL/api/status" | jq -er '.data.quota_per_unit')
expires_at=$(( $(date +%s) + 3600 ))
quota=$(( 5 * quota_per_unit ))

create_payload=$(jq -n \
  --arg name "$name" \
  --argjson expires "$expires_at" \
  --argjson quota "$quota" '{
    name: $name,
    expired_time: $expires,
    remain_quota: $quota,
    unlimited_quota: false,
    model_limits_enabled: false,
    model_limits: "",
    allow_ips: "",
    group: "default",
    cross_group_retry: false,
    smart_routing: false,
    smart_route_tiers: ""
  }')

created=$(curl -fsS -X POST "$BASE_URL/api/token/" \
  "${auth[@]}" -H "Content-Type: application/json" \
  -d "$create_payload")
jq -e '.success == true' <<< "$created" >/dev/null

found=$(curl -fsS --get "$BASE_URL/api/token/search" \
  "${auth[@]}" --data-urlencode "keyword=$name" \
  --data-urlencode "p=1" --data-urlencode "size=10")
token_id=$(jq -er --arg name "$name" '
  [.data.items[] | select(.name == $name)]
  | if length == 1 then .[0].id
    else error("expected exactly one matching API key")
    end
' <<< "$found")

stored_key=$(curl -fsS -X POST "$BASE_URL/api/token/$token_id/key" \
  "${auth[@]}" | jq -er '.data.key')
api_key="sk-${stored_key#sk-}"
# Replace this no-op with your secrets-manager command.
: "$api_key"
unset stored_key api_key

current=$(curl -fsS "$BASE_URL/api/token/$token_id" "${auth[@]}")
update_payload=$(jq --argjson quota "$((10 * quota_per_unit))" '.data | {
  id, name, expired_time, remain_quota, unlimited_quota,
  model_limits_enabled, model_limits, allow_ips, group,
  cross_group_retry, smart_routing, smart_route_tiers
} | .remain_quota = $quota' <<< "$current")

curl -fsS -X PUT "$BASE_URL/api/token/" \
  "${auth[@]}" -H "Content-Type: application/json" \
  -d "$update_payload" | jq -e '.success == true' >/dev/null

curl -fsS -X PUT "$BASE_URL/api/token/?status_only=true" \
  "${auth[@]}" -H "Content-Type: application/json" \
  -d "{\"id\":$token_id,\"status\":2}" \
  | jq -e '.success == true' >/dev/null

delete_token
token_id=""
trap - EXIT
echo "API key lifecycle completed"

Popular Models

OpenAI SDK Usage

System API

Text Series

Embedding Series

Image Series

Video Series

Others

Overview

Mutable fields

Create a standard API key

List and search

Read and reveal

Safely update a key

Enable or disable

Delete keys

Complete lifecycle script

​Overview

​Mutable fields

​Create a standard API key

​List and search

​Read and reveal

​Safely update a key

​Enable or disable

​Delete keys

​Complete lifecycle script

Overview

Mutable fields

Create a standard API key

List and search

Read and reveal

Safely update a key

Enable or disable

Delete keys

Complete lifecycle script