> ## Documentation Index
> Fetch the complete documentation index at: https://www.octogen.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate with the StoreRouter Platform API

> Learn how to create a Platform API key, configure OCTO_API_KEY in your environment, and send it as a Bearer token to authenticated endpoints.

Most requests to the StoreRouter Platform Catalog API require a valid API key. Keys are issued per organization through StoreRouter 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.

[`GET /domains`](/docs/api-reference/list-domains), `POST /products/lookup`, and `POST /products/search` also support a limited keyless trial. Include an API key for production workloads, higher limits, and access to the complete `/v1` surface.

## API key format

StoreRouter 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

<Steps>
  <Step title="Create a key in StoreRouter Platform">
    Log in to StoreRouter Platform and navigate to **API Keys**. Generate a new key and copy it immediately — the secret portion is only shown once.
  </Step>

  <Step title="Set the environment variable">
    Add your key to your environment so the SDKs can pick it up automatically:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Verify the setup">
    Confirm the key works with a small product search:

    ```bash theme={null}
    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.
  </Step>
</Steps>

## Attach the key to requests

Send the key as a Bearer token in the `Authorization` header on authenticated requests:

```http theme={null}
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:

```python theme={null}
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>")
```

```typescript theme={null}
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 StoreRouter 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.

<Warning>
  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.
</Warning>

## 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 StoreRouter 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. |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.