Skip to main content
Every request to the Octogen Platform Catalog API must include a valid API key. Keys are issued per organization through the partner portal and grant access only to the catalogs assigned to that organization. This page explains the key format, how to configure your environment, and what to do when authentication fails.

​
API key format

Octogen Platform API keys follow this structure: 
octo_live_<32-hex-id>_<base64url-secret>
Keep your key private. Do not commit it to source control or expose it in client-side code.

​
Set up your API key

1

Create a key in the partner portal

Log in to the Octogen partner portal and navigate to API Keys. Generate a new key and copy it immediately — the secret portion is only shown once.
2

Set the environment variable

Add your key to your environment so the SDKs can pick it up automatically:
export OCTO_API_KEY="octo_live_<your-key>"
For long-lived deployments, set this in your server’s secrets manager or environment configuration rather than in shell profiles.
3

Verify the setup

Confirm the key works by listing your catalogs:
curl -sS https://api.octogen.ai/v1/catalogs \
  -H "Authorization: Bearer $OCTO_API_KEY"
A successful response returns a JSON array of catalogs. An empty array means your organization has no active catalog grants — not an authentication failure.

​
Attach the key to requests

Send the key as a Bearer token in the Authorization header on every request: 
Authorization: Bearer octo_live_<your-key>
Content-Type: application/json

​
SDKs handle this automatically

If you use the Python or TypeScript SDK, authentication is handled for you. The client reads OCTO_API_KEY from the environment by default, or you can pass the key explicitly: 
from octogen_ai_sdk import OctogenClient

# Reads OCTO_API_KEY from the environment automatically
client = OctogenClient()

# Or pass the key directly
client = OctogenClient(api_key="octo_live_<your-key>")

import { OctogenClient } from "@octogen-ai/sdk";

// Reads OCTO_API_KEY from the environment automatically
const client = new OctogenClient();

// Or pass the key directly
const client = new OctogenClient({ apiKey: "octo_live_<your-key>" });

​
Rotate and revoke keys

Rotate keys from the API Keys section of the partner portal. When you deactivate a key, it is revoked immediately — the next request using that key returns a 401 error. Issue a replacement key before deactivating the old one to avoid downtime.
Deactivating a key takes effect on the next API request. There is no grace period. Always create and deploy a replacement key before revoking the old one.

​
Error reference

StatusMeaningWhat to do
401The key is missing, malformed, or has been revoked.Check that OCTO_API_KEY is set correctly and that the key has not been deactivated in the portal.
403The key is valid, but your organization is not authorized for this resource.Confirm that your organization is provisioned as a Catalog Partner and that the catalog has been granted to your account.
API keys are organization-scoped. A key can only access catalogs explicitly granted to the organization that owns it. If you believe a catalog should be available but you receive a 403, contact Octogen to verify the grant.