API Reference

Authentication

InferexAI uses JWT-based API keys. Every request must include a valid key in the Authorization header. Keys support optional expiry, scopes, and per-key rate limits.

Authorization header

text

Authorization: Bearer sk-live-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Using the InferexAI SDK

Python

from inferexai import InferexAI

client = InferexAI(api_key="sk-live-your-key-here")

Creating a key

Create keys from Dashboard → API Keys or via the portal API. You can set a name, expiry date, and scopes at creation time.

bash

curl https://api.inferexai.in/portal/keys \
  -X POST \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-voice-agent",
    "expires_at": "2027-01-01T00:00:00Z",
    "scopes": ["chat", "completions"]
  }'

response.json

{
  "api_key": "sk-live-eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "prefix": "sk-live-a1b2c3d4"
}

Key scopes

Scopes restrict what a key can access. Use the wildcard * to allow all endpoints (default), or grant only the scopes your application needs.

Scope	Allows
`*`	All endpoints (wildcard — default when no scopes specified)
`chat`	POST /v1/chat/completions
`completions`	POST /v1/completions (legacy)
`embeddings`	POST /v1/embeddings
`models`	GET /v1/models

If a key lacks the required scope, the gateway returns:

text

HTTP 403
{"detail": "API key missing 'chat' scope"}

Key expiry

Set expires_at (ISO 8601 UTC) when creating a key to enforce mandatory rotation. Expired keys are rejected immediately with:

text

HTTP 401
{"detail": "API key expired — rotate your key at /dashboard/keys"}

Keys without an expires_at never expire unless revoked manually.

Per-key rate limits

Admins can set two independent rate limits on each key. Both limits apply independently — breaching either returns HTTP 429.

RPM — Requests per minute

Fixed-window counter reset every 60 seconds. Protects against burst traffic.

TPD — Tokens per day

Cumulative prompt+completion tokens. Resets at midnight UTC. Protects against runaway token consumption.

RPM exceeded:

text

HTTP 429
Retry-After: 42
X-RateLimit-Limit-RPM: 60

{"detail": "rate limit exceeded — too many requests per minute"}

TPD exceeded:

text

HTTP 429
X-RateLimit-Limit-TPD: 1000000
X-RateLimit-Used-TPD: 1000000

{"detail": "daily token limit exceeded — resets at midnight UTC"}

Use the Retry-After header (seconds) to back off before retrying after an RPM limit. See the Rate Limiting guide for retry patterns.

How API keys work

JWT-signed

Every key is an HS256 JWT. The payload contains your user ID, a unique key ID (jti), and an issue timestamp.

Revocable

Revoke any key from Dashboard → API Keys. Revoked keys are rejected immediately — even cached requests fail.

Key prefix

The prefix (e.g. sk-live-a1b2c3d4) appears in usage logs so you can identify which key made each request.

Visible in dashboard

Full key tokens are stored and visible in your dashboard. There is no "shown once" restriction.

Best practices

✓Never commit API keys to source control. Use environment variables or a secrets manager.

✓Create separate keys per application and environment (dev, staging, prod).

✓Use scopes to restrict each key to only the endpoints it needs.

✓Set expires_at on long-lived service keys to enforce periodic rotation.

✓Monitor per-key usage in the Observability dashboard to detect anomalies.

✓Revoke compromised keys immediately from the dashboard.

.env

# .env
INFEREXAI_API_KEY=sk-live-your-key-here
INFEREXAI_BASE_URL=https://api.inferexai.in/v1