Authenticate with the Octogen Platform API

Every request to the Octogen Platform Catalog API must include a valid API key. Keys are issued per organization through Octogen Platform. Developer API keys can search and browse every active crawled catalog and can never access merchant catalogs. 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

Create a key in Octogen Platform

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

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.

Verify the setup

Confirm the key works with a small product search:

curl -sS https://api.octogen.ai/v1/products/search \
  -H "Authorization: Bearer $OCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"shirt","limit":1}'

A successful response returns an items array. Catalog enumeration is not required to search across the policy-wide crawled catalog set.

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 Octogen Platform. 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

Status	Meaning	What to do
`401`	The 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 Octogen Platform.
`403`	The key is valid, but your organization is not authorized for this resource.	Inspect `detail` and confirm the key belongs to a Developer organization.

API keys are organization-scoped. Search/browse access for Developers covers active crawled catalogs only. BigQuery listing access remains separately granted.

Get Started

SDKs

MCP Integration

Guides

Authenticate with the Octogen Platform API

API key format

Set up your API key

Attach the key to requests

SDKs handle this automatically

Rotate and revoke keys

Error reference

​API key format

​Set up your API key

​Attach the key to requests

​SDKs handle this automatically

​Rotate and revoke keys

​Error reference

API key format

Set up your API key

Attach the key to requests

SDKs handle this automatically

Rotate and revoke keys

Error reference