Authentication
Authenticate with the API key delivered after payment.
After manual setup delivery, use the OpenAI-compatible API key and base URL from trusted server-side code. Keep credentials out of clients, then rotate or revoke scoped keys without disrupting unrelated services.
Last updated: July 6, 2026. Examples use safe placeholders and do not include real credentials or customer data.
Server-side rule
Treat delivered API keys like production credentials. Keep them in trusted server environments and call your own backend from browsers or mobile apps.
Setup path
Six steps from manual delivery to safe rotation.
Step 1
Receive API setup
Complete package payment and wait 10 minutes to 5 hours for admin delivery of the API key, base URL, setup files, activation date, start date, and end date.
Step 2
Create a scoped key
After setup is delivered, keep the delivered key server-side or create a scoped key for one service, one environment, and the smallest endpoint scopes that service needs.
Step 3
Store it server-side
Save the full value in a secret manager or deployment environment variable. Do not ship it to browsers or mobile clients.
Step 4
Send a Bearer token
Attach the key in the Authorization header for each server-side request to the delivered OpenAI-compatible API base URL.
Step 5
Watch auth failures
Use stable error codes to distinguish missing keys, inactive keys, expired keys, IP policy failures, and missing scopes.
Step 6
Rotate before risk grows
Create a replacement key, deploy it, confirm traffic moves, then revoke the old key.
API key format
Keys identify environment and secret material separately.
The manually delivered API key arrives by email only. Self-service scoped keys start with an unlimitedcodex prefix, include an environment segment, and end with generated secret material; their full value is shown once at creation.
| Segment | Example | Purpose |
|---|---|---|
| Prefix | ucx | Identifies the value as an unlimitedcodex API key. |
| Environment | dev, test, or live | Keeps local, staging, and production credentials separate. |
| Secret value | Generated random value | Shown once at creation, then stored as a secure hash. |
| Display prefix | First safe characters | Used in logs and dashboards to identify a key without revealing the full credential. |
Use placeholders such as ucx_live_placeholder_value in docs and tests. Never paste a real key into examples, issue trackers, analytics, or support messages.
Bearer token usage
Send the key in the Authorization header.
Server-side callers should read the delivered or scoped key from an environment variable and send it as a Bearer token with each API request.
Use HTTPS for all API requests.
Send the full key only in the Authorization header.
Keep content type headers separate from authentication.
Return sanitized errors to client applications.
# Server-side environment only UCX_API_KEY=ucx_live_placeholder_value
const response = await fetch("https://unlimitedcodex.com/v1/models", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.UCX_API_KEY}`
}
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.error?.code ?? "api_request_failed");
}Environment variables
Keep credentials out of client bundles.
Delivered API keys belong in backend processes, serverless functions, and secure workers. Browser code should call your backend, not unlimitedcodex directly.
Local development
Use a development or test key in a local-only env file that is ignored by git.
Preview deployments
Use a separate preview key so staging traffic cannot affect production credentials.
Production servers
Use your hosting provider's encrypted environment store or a dedicated secret manager.
Client applications
Do not expose API keys in frontend env vars, browser storage, mobile bundles, or static files.
Key rotation
Rotate by adding first, then revoking.
Avoid production interruption by deploying a replacement key before revoking the old one. Use display prefixes and request logs to confirm the cutover.
# Rotation checklist 1. Create a replacement key with the same required scopes. 2. Save it as the next server-side environment value. 3. Deploy the service and confirm traffic uses the new prefix. 4. Revoke the old key after traffic has moved. 5. Monitor 401 and 403 responses for stale deployments.
Common auth errors
Read the status and error code before retrying.
Authentication errors use stable response codes so your integration can distinguish missing credentials from scope, status, allowlist, and verification issues.
| Status | Code | Common cause | Next action |
|---|---|---|---|
| 401 | invalid_api_key | The Authorization header is missing, malformed, or contains an unknown key. | Check the Bearer token, environment variable name, and deployment secret. |
| 403 | inactive_api_key | The key exists but is not active. | Use an active key or create a replacement key for the service. |
| 403 | expired_api_key | The key has passed its expiration time. | Rotate the credential and deploy the new value. |
| 403 | ip_not_allowed | The request came from an IP address outside the key allowlist. | Update the allowlist or send traffic from an approved server. |
| 403 | insufficient_scope | The key does not include the scope required by the endpoint. | Create or update a key with the specific scope your endpoint needs. |
| 503 | api_key_store_unavailable | Database-backed key verification is temporarily unavailable or not configured. | Retry later for temporary failures, or check environment configuration in non-production environments. |
Recommended security practices
Design authentication for containment.
A good key strategy limits the blast radius of mistakes. Separate environments, scopes, services, and owners so one key never has more access than it needs.
Use separate keys for development, staging, and production.
Create one key per service so rotation and revocation are targeted.
Grant only the endpoint scopes the service needs.
Keep keys out of client-side code, mobile apps, logs, and public repositories.
Store the full key in a secret manager or deployment environment variable.
Rotate keys on a schedule and immediately after suspected exposure.
FAQ
Authentication questions.
Do I get an API key instantly after checkout?
No. Setup is prepared manually after payment. Expected delivery is 10 minutes to 5 hours and includes the API key, base URL, setup files, activation date, start date, and end date.
Where should I store an API key?
Store the full key in a server-side secret manager or deployment environment variable. Never place it in browser code, mobile apps, public repositories, or client-visible configuration.
Can I view a full API key after creation?
No. The manually delivered API key arrives by email only. Self-service scoped keys are shown once at creation; after that, use the safe display prefix while the platform stores a secure hash.
Which scopes can a key use?
API keys can be scoped for chat:write, embeddings:write, images:write, and usage:read. Grant the smallest scope set required by the service.
How do I rotate a production key?
Create a replacement key with the required scopes, deploy it as a new server-side environment value, confirm traffic uses the new prefix, then revoke the old key.
Free tools
Try these before your first live request
Client-side helpers for migration, validation, quota planning, and 429 troubleshooting.
Migration Generator
Generate or transform OpenAI SDK snippets to unlimitedcodex base URL, keys, and scopes.
Request Validator
Validate chat, embeddings, and image JSON payloads against unlimitedcodex OpenAI-compatible rules.
429 Decoder
Paste a 429 response body and headers to classify rate-limit vs quota pressure and see retry guidance.
Scope Configurator
Select workloads and output least-privilege scopes, .env.example, and a rotation checklist.
Rate Limit Planner
Plan backoff settings and quota monitoring checklist from expected RPS and team size.
Next step
Pair authentication with quota and error handling.
Once keys are server-side and scoped, review unlimited token usage, 4 concurrent connections, common API errors, and webhook endpoint setup before customer-facing traffic grows.