Authentication

How to authenticate with the PolarGrid API

Authentication

All PolarGrid API requests require authentication using an API key.

API Keys

API keys are created in the PolarGrid Console and start with pg_.

Creating a Key

1. Open the API Keys page — either click Generate API Key (or Manage API Keys) on the Dashboard Overview, or go to Settings → API Keys in the sidebar
2. Click Generate New Key
3. Give it a descriptive name (e.g., “Production App”, “Development”)
4. Select permissions: read-write (default), read-only, or admin
5. Copy the key immediately — it won’t be shown again

Using Your Key

The SDKs handle authentication automatically — just pass your API key:

JavaScript

const client = await PolarGrid.create({
  apiKey: 'pg_your_api_key',
});

Raw HTTP (cURL)

Send your pg_* API key directly to the edge. Pick a region with the autorouter (one request) or pin one.

export API_KEY="pg_your_api_key"

# Option A — auto: ask the autorouter for the best edge for the caller.
# Returns {region, name, endpoint, ttl}. The endpoint is the actual base URL.
EDGE=$(curl -s https://autorouter.polargrid.ai/v1/route | jq -r .endpoint)

# Option B — pinned: hardcode a region instead
# EDGE="https://api.yto-01.edge.polargrid.ai"

# Call the edge directly with your API key.
curl -s -X POST "$EDGE/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen-3.5-9b", "messages": [{"role": "user", "content": "Hi"}]}'

The autorouter (autorouter.polargrid.ai) is a discovery endpoint — it serves GET /v1/route only. It does not proxy /v1/chat/completions, /v1/models, or any other inference traffic; POST against it is rejected by CloudFront with 403.

Playground vs API

The Playground in the Console uses your real pg_* API key — the same key from Creating a Key above. There is no separate “playground token”.

1. Open the Playground

   Click Playground in the Console sidebar.

2. Select your key

   Pick a saved key from the Playground’s API key dropdown, or paste one manually.

Under the hood, the Playground sends your API key directly to the nearest edge — the same flow as a raw cURL call.

Environment Variables

We recommend storing your API key in an environment variable:

export POLARGRID_API_KEY="pg_your_api_key"

The SDKs automatically read from this variable:

JavaScript

// No need to pass apiKey if POLARGRID_API_KEY is set
const client = await PolarGrid.create();

Permission Levels

Level	Description
read-write	Default for keys minted from the Console. Recommended for typical SDK / API usage.
read-only	Same data-plane access today; intended for callers that should not mint LiveKit room tokens (/v1/tokens).
admin	Same data-plane access plus the ability to mint LiveKit room tokens.

The inference endpoints (/v1/chat/completions, /v1/completions, /v1/models, /v1/audio/*) are not currently scope-gated — any active key can call them. Scope enforcement is presently scoped to /v1/tokens. Default to read-write unless you have a specific reason to narrow.

Troubleshooting Auth Errors

HTTP Code	Error	Cause	Fix
401	Invalid API key	API key not recognized, revoked, or deleted	Verify the key is correct and active in the Console. If revoked, generate a new key
403	{"Message": null} or Forbidden	Request blocked by infrastructure (CloudFront/WAF) before reaching the auth service	Ensure you’re using the correct endpoint URL and that your request includes valid headers. See Regions

Token Lifespan

When you authenticate with a pg_* API key, the auth service issues a session token (JWT) and a refresh token.

Token	Default Lifetime	Purpose
Session (JWT)	24 hours	Authorizes inference requests on the edge
Refresh	30 days	Extends the session without re-authenticating

The SDK handles token refresh automatically — when a session token expires, it uses the refresh token to obtain a new one without interrupting your application.

For most use cases, including long-running voice sessions (call centers, 24/7 agents), the 24-hour session lifetime with automatic refresh is sufficient. No manual token management is required.

Security Best Practices

Never commit API keys to source control or expose them in client-side code.

• Use environment variables for API keys
• Rotate keys periodically
• Use separate keys for development and production
• Revoke keys immediately if compromised

CLI Authentication

The CLI supports two authentication methods:

Browser Login (Interactive)

polargrid login

Opens your browser for OAuth authentication. Best for development.

API Key (CI/CD)

export POLARGRID_API_KEY="pg_your_api_key"
polargrid test inference --region toronto --prompt "Hello"

No login needed — just set the environment variable.