Provider Key API

Provider Key API

A Provider Key is an API key the tenant holds with an upstream provider. XSI groups keys into key pools by Level and routes requests to the matching pool by model. All endpoints require the caller to be a tenant owner (ID == OID; root is also an owner), and only the tenant's own keys are visible and manageable. Calls from sub-accounts return 403 Only account owner can access this endpoint.

export XSI_BASE_URL="https://api.xsicontrol.com"   # Or your own API domain
export XSI_API_KEY="sk-Xvs..."                     # Key of the tenant owner

Upstream keys are stored encrypted with the tenant key, and the tenant key is encrypted with the owner's API key, so these endpoints must be called with the owner's own key.

Endpoints at a glance

Method and pathDescription
GET /x-keysList keys (with filtering and pagination)
GET /x-keys/{id}, /x-keys/L{level}, /x-keys/{provider substring}Filter by ID, Level or provider
POST /x-keysAdd a key
PUT /x-keys/{id} (or POST)Partial update
DELETE /x-keys/{id}Delete
POST /x-keys/{id}/sleepPut to sleep manually for 32 hours
POST /x-keys/{id}/wakeWake a sleeping key

Key object

FieldDescription
IDKey ID
NameNote; also used to identify the provider for automatic Level mapping
LevelKey pool group; default 1
ProviderUpstream base URL, e.g. https://api.openai.com; may include a path prefix
SecretKeyUpstream key in plaintext (returned only in full mode)
PartialKeyLast 20 characters of the upstream key
ConfigProvider-specific configuration, see below (returned only in full mode)
ProviderTypeValue of Config.provider_type (omitted when empty)
NoSleepWhen true, excluded from automatic sleep
Statustrue enabled, false disabled
Sleeping, SleepModeWhether the key is sleeping; auto or manual
CreatedAtCreation time

List keys

curl "$XSI_BASE_URL/x-keys?fields=summary&level=1&page=1&size=50" \
  -H "Authorization: Bearer $XSI_API_KEY"
ParameterDescription
id, levelExact match
providerProvider URL substring match, e.g. provider=api.openai.com
page, sizePagination; at most 8192 items per page
fieldssummary (or list, lite) returns a summary only; when omitted, defaults to full and returns the plaintext upstream key and decrypted Config
Always use fields=summary for routine queries, and use full only when you really need to export plaintext.
  • The response is always an array; [] when the ID does not exist. Results are sorted by ID ascending.
  • X-Total-Count is returned when filter or pagination parameters are present; paginated responses also include X-Page, X-Per-Page and X-Total-Pages.
  • The path forms /x-keys/L2 (filter by Level) and /x-keys/openai (filter by provider substring) are not paginated.

Add a key

curl -X POST "$XSI_BASE_URL/x-keys" \
  -H "Authorization: Bearer $XSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "openai-main",
    "Level": 1,
    "Provider": "https://api.openai.com",
    "SecretKey": "sk-proj-..."
  }'
FieldRequiredDescription
ProviderYesAn http or https URL that includes a host; must not point to XSI itself
SecretKeyYesUpstream key, at least 20 characters
LevelNoGroup; 1 if omitted or 0
NameNoNote
NoSleepNoExempt from automatic sleep
configNoProvider-specific configuration
  • New keys are always enabled; to disable one, send PUT {"Status": false} after creation.
  • The same upstream key can be added more than once (for example, on several Levels).

Response:

{
  "Action": "add",
  "Key": {"ID": 12, "Name": "openai-main", "Level": 1, "Provider": "https://api.openai.com", "PartialKey": "...", "Status": true},
  "Message": "Key added successfully",
  "AutoMapping": {"added": ["gpt*", "o*"], "removed": []}
}

Automatic Level mapping

After a key is added or updated, if that Level has no LEVEL_MAPPER entries yet, XSI automatically writes model patterns based on the provider, for example https://api.openai.com β†’ gpt*, o*, chatgpt*, text-embedding*, tts*, whisper*; https://api.anthropic.com β†’ claude*; https://api.x.ai β†’ grok*; https://api.deepseek.com β†’ deepseek*. The provider is matched first by an exact Provider match (character for character, without a trailing slash), then by Name. If the provider cannot be identified and this is the tenant's only Level, *=<Level> is written. The result appears in AutoMapping in the response and can be adjusted at any time through the Tenant Configuration API.

Provider configuration config

Most providers need only Provider and SecretKey: XSI picks the path mapping and authentication method from the provider hostname. For supported hosts, see Supported Providers. Providers that need extra information are specified with config.provider_type:

Azure OpenAI / Azure AI

{
  "Name": "azure-eastus",
  "Level": 3,
  "Provider": "https://my-resource.openai.azure.com",
  "SecretKey": "<azure-api-key>",
  "config": {
    "provider_type": "azure",
    "model_mapping": {"gpt-6.2-sol": "my-gpt-deployment", "text-embedding-3-*": "embed-deployment"},
    "api_versions": {"chat": "2025-04-01-preview", "responses": "preview"}
  }
}
  • model_mapping: maps model names to deployments; wildcards are supported.
  • api_versions: sets api-version per API type (chat, responses, embeddings, images, audio, realtime); when not configured, the environment variable AZURE_AI_APIVERSION_<TYPE> is used.
  • If the provider host contains .azure.com, paths are rewritten in Azure OpenAI style; otherwise the Azure AI inference API (/models/chat/completions) is used.
  • The auth header is api-key.

Google Vertex AI

{
  "Name": "vertex",
  "Level": 4,
  "Provider": "https://aiplatform.googleapis.com",
  "SecretKey": "vertex-service-account-placeholder",
  "config": {
    "provider_type": "vertex",
    "base_url": "https://aiplatform.googleapis.com/v1/projects/my-project/locations/global",
    "project_id": "my-project",
    "client_email": "[email protected]",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
  }
}
  • All four fields are required. XSI signs a JWT with the service account to obtain an access token (cached for 59 minutes); private_key is stored encrypted.
  • The SecretKey field must still contain at least 20 characters; a placeholder value is fine.

OpenAI Live-compatible upstreams

"provider_type": "openai-live" allows keys other than api.openai.com to serve Live sessions.

Other provider_type values have no special behavior and are treated as regular providers.

Update a key

curl -X PUT "$XSI_BASE_URL/x-keys/12" \
  -H "Authorization: Bearer $XSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Level": 2, "NoSleep": true}'
  • Name, Level, Provider, SecretKey, NoSleep, Status and config can be updated; only fields present in the request are changed.
  • config is replaced as a whole; passing {} clears it.
  • "Status": true also wakes a sleeping key; "Status": false disables the key and removes it from rotation.
  • Automatic Level mapping also runs after an update.

Delete a key

curl -X DELETE "$XSI_BASE_URL/x-keys/12" -H "Authorization: Bearer $XSI_API_KEY"

This is a permanent delete. Before deleting, make sure the Level still has other available keys, and check whether LEVEL_MAPPER still has entries pointing to that Level.

Sleep and wake

MechanismTriggerDuration
Automatic sleepThe upstream returns a status in STATUS_CODES (default 429,401,402,503,408,524), the Level has more than one key, the key's Level > 0, and NoSleep is not setKEY_BACK minutes (default 60)
Manual sleepPOST /x-keys/{id}/sleepFixed 32 hours
WakePOST /x-keys/{id}/wake, or PUT {"Status": true}Immediate
Automatic disable / deleteThe upstream returns a status in AUTO_DISABLE_KEY_STATUS / AUTO_DELETE_KEY_STATUS (off by default)Disabled keys stay disabled until re-enabled manually; deleted keys must be added again
  • When only one available key remains on a Level, it is never put to sleep automatically, and automatically slept keys in the same group are woken.
  • Automatic disable and delete never apply to the last enabled key on a Level.
  • Disabled keys cannot be put to sleep manually (409); keys that are not sleeping cannot be woken (409 Key is not sleeping.).

Errors

StatusBody
400Provider is required, Provider must be a valid URL, Secret key must be at least 20 characters long, config.provider_type must be a string, Invalid Key ID.
403Only account owner can access this endpoint, Provider ... is not allowed (self-reference)
404Key not found.
409Disabled key cannot be manually slept., Key is not sleeping.
500Failed to decrypt key (use the owner's own key)

Security recommendations

  • Use separate Levels for different providers, environments or cost tiers so you can switch and monitor them independently.
  • Grant access to these endpoints only to the owner key, and keep the owner key on the server or in a secrets manager.
  • Use fields=summary for queries. full mode and the sleeping and disabled key lists in GET /x-conf all return upstream keys in plaintext.
  • Rotate upstream keys regularly: update SecretKey with PUT /x-keys/{id}; there is no need to recreate the key.