Skip to main content
POST
/
v1
/
api-keys
/
sub-keys
Create Sub-API Key
curl --request POST \
  --url https://api.io.solutions/v1/api-keys/sub-keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "description": "<string>",
  "scopes": [
    "<string>"
  ],
  "allowed_models": [
    "<string>"
  ],
  "credit_limit": 1,
  "credit_refresh_cycle": "monthly",
  "expires_at": "2023-11-07T05:31:56Z",
  "key_prefix": "<string>"
}
'
{
  "status": "succeeded",
  "data": {
    "key_id": "71775d2e-fbcc-4ef4-aa30-8aaeb82062c0",
    "value": "acme-v2-eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "display": "acme-v2-eyJh...c0eQ",
    "admin_user_id": "95ce9361-447f-4ec0-a698-764c2a2d15b9",
    "description": "Partner integration key",
    "allowed_models": [
      "meta-llama/Llama-3.3-70B-Instruct"
    ],
    "credit_limit": 10,
    "credit_refresh_cycle": "monthly",
    "expires_at": "2026-08-20T00:00:00"
  }
}
The full key value is returned only once at creation time. Store it securely — it cannot be retrieved again. Only the truncated display string is stored and returned in subsequent list or usage calls.
Only admin API keys can create sub-keys. A sub-key cannot create further sub-keys. If you authenticate with a sub-key, the endpoint returns 403 Forbidden.

​
Key fields

  • description – A human-readable label to identify the key’s purpose or owner.
  • allowed_models – An optional list of model identifiers (e.g. "meta-llama/Llama-3.3-70B-Instruct") that this sub-key is permitted to call. If omitted, all models available to the admin are accessible. Requests to unlisted models are rejected with 403 Forbidden.
  • credit_limit – Maximum IO Intelligence credits the sub-key may consume per refresh cycle. Once the limit is reached the key is automatically blocked until the cycle resets or the admin raises the limit via PATCH. Set to null to impose no per-key cap.
  • credit_refresh_cycle – How often the usage counter resets: "8h", "daily", "weekly", or "monthly" (default).
  • expires_at – ISO 8601 date-time for key expiry, or the literal string "never" for a non-expiring key. Defaults to 180 days from creation when omitted.
  • key_prefix – An optional lowercase slug (2–8 chars) prepended to the generated key value (e.g. "acme" produces acme-v2-eyJ...). Defaults to the standard io-v2 prefix when omitted. Cannot start with "io" or contain version markers like "-v2".

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Headers

​
x-api-key
string
required

Admin API key with full access. Sub-keys created by this key inherit its credit pool. Admin API key (io.net Intelligence)

Body

application/json
​
description
string
required

A human-readable label for the sub-key.

​
scopes
string[] | null

Access scopes. Defaults to ["intelligence"] if omitted.

​
allowed_models
string[] | null

List of model identifiers this sub-key is permitted to use. If omitted, all models available to the admin are allowed.

​
credit_limit
number | null

Maximum credits (in IO Intelligence credits) the sub-key may consume per refresh cycle. Null means no per-key limit — the admin's overall balance applies.

Required range: x >= 0
​
credit_refresh_cycle
enum<string>
default:monthly

How often the sub-key's credit_used counter resets. Defaults to "monthly".

Available options:
8h,
daily,
weekly,
monthly
​
expires_at

Expiry date-time for the key. Pass "never" for a non-expiring key. Defaults to 180 days from creation if omitted.

​
key_prefix
string | null

Custom lowercase slug prepended to the key (e.g. "acme" produces "acme-v2-..."). Must be 2–8 lowercase alphanumeric characters with optional internal hyphens. Cannot start with "io" (reserved) or contain version markers such as "-v2".

Required string length: 2 - 8
Pattern: ^[a-z][a-z0-9-]*[a-z0-9]$

Response

Sub-API key created successfully

​
status
string
Example:

"succeeded"

​
data
SubKeyCreated · object