Skip to main content

​
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. Go to Settings → API Keys in the console
  2. Click Generate New Key
  3. Give it a descriptive name (e.g., “Production App”, “Development”)
  4. Select permissions: read-only, read-write, 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: 
const client = await PolarGrid.create({
  apiKey: 'pg_your_api_key',
});

​
Raw HTTP (cURL)

For raw API access, exchange your API key for a JWT via the PolarGrid app, then use that token for edge requests: 
# Exchange API key for a JWT
TOKEN=$(curl -s -X POST https://app.polargrid.ai/api/auth/inference-token \
  -H "Authorization: Bearer $API_KEY" | jq -r .token)

# Use the JWT to call an edge node
curl -s -X POST https://api.yto-01.edge.polargrid.ai/v1/chat/completions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "Meta-Llama-3.1-8B-Instruct", "messages": [{"role": "user", "content": "Hi"}]}'

​
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: 
// No need to pass apiKey if POLARGRID_API_KEY is set
const client = await PolarGrid.create();

​
JWT Token Exchange

Under the hood, the SDKs exchange your API key for a short-lived JWT token via the PolarGrid app (https://app.polargrid.ai/api/auth/inference-token). This happens automatically — you don’t need to manage tokens yourself. The JWT is cached and refreshed automatically before it expires. The token expiry is included in the API response.

​
Manual Token Exchange

If you’re building a custom integration without an SDK:
  1. Get a token: POST https://app.polargrid.ai/api/auth/inference-token with your API key in the Authorization: Bearer header
  2. Discover edges: The token response includes available edge endpoints (see Regions for the full list)
  3. Use the token: Include Authorization: Bearer <token> in all edge API requests

​
Permission Levels

LevelDescription
read-onlyCan make inference requests only
read-writeCan make requests and manage models
adminFull access including API key management

​
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
  • Use read-only keys when possible
  • 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.