Authentication

The Grid issues two types of API keys plus OAuth access tokens for programmatic account control. This page covers generation, use, rotation, and the agent onboarding path.

Three ways to authenticate

Mechanism	Where	Use when
Consumption API key	Consumption API	Inference (chat completions, messages)
Trading signing key (Ed25519)	Trading API	Markets, orders, balances, transfers
OAuth access token (grid_at_*)	Platform API	Device login, create keys, account settings

Most agents and integrations run the programmatic onboarding flow: OAuth on the Platform API → create consumption and signing keys → call Consumption and Trading.

Two credential types (inference vs trading)

Key type	API used	Auth scheme	What it covers
Consumption key	Consumption API	Bearer header or x-api-key header	Inference only. Chat completions on the OpenAI-compatible host, messages on the Anthropic Messages host.
Trading key	Trading API	Ed25519-signed requests	Everything beyond inference: instrument specifications, market data, balances, past trades, transfers, and order placement.

If you only consume inference and let Auto Mode buy on your behalf, a Consumption key is enough. The moment you want to read your account balance, fetch instrument specifications programmatically, list past purchases, or place orders yourself, you need a Trading key. Trading keys cover the entire Trading API surface, not just order placement.

Both key types can be created in the dashboard at app.thegrid.ai/profile/api-keys or programmatically on the Platform API after OAuth login (keys:manage scope). See Platform API — Consumption API keys and Trading signing keys.

OAuth access tokens (Platform API)

OAuth 2.0 device flow (RFC 8628) is the recommended way for agents and automation to sign in. Start with POST /v1/oauth/device/code on the Platform API (see Programmatic onboarding or the Platform API reference).

That yields grid_at_* bearer tokens. Tokens are scoped — for example keys:manage to create consumption and signing keys, account:read / account:write for account settings.

OAuth tokens are not a drop-in replacement for consumption keys on the Consumption API. After login, create a consumption API key on the Platform API, then use that key as Authorization: Bearer on https://api.thegrid.ai/v1.

Full OAuth endpoints, scopes, and request schemas: Platform API.

Consumption keys

A standard Bearer token. The same key value works on both the OpenAI-compatible host and the Anthropic Messages host. Only the header name changes.

Generate a Consumption key

Dashboard:

1. Sign in at app.thegrid.ai.
2. Open Profile > API Keys.
3. Click Create new key, name it something you recognize later (one key per project is a sensible default), and copy the value. The full key is shown once.

Programmatic (after OAuth login):

curl -sS -X POST "https://platform.api.thegrid.ai/v1/api-keys" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"api_key": {"name": "my-agent"}}'

Requires keys:manage on the access token. The raw key is in data.key in the response (shown once).

Use a Consumption key

On the OpenAI-compatible host (https://api.thegrid.ai/v1), pass the standard Bearer header:

curl -L https://api.thegrid.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "text-prime", "messages": [{"role": "user", "content": "Hello"}]}'

On the Anthropic Messages host (https://messages-beta.api.thegrid.ai/v1), pass the Anthropic-style header instead. Same key value, different header name:

x-api-key: YOUR_API_KEY

Trading keys

The Trading API uses Ed25519 signature authentication. Every request is signed with your private key, and we verify it against the public key you registered in the dashboard.

Generate an Ed25519 keypair

Generate the keypair locally using a public Ed25519 library. The private key never leaves your machine; only the public key gets registered with us.

Python

Uses the cryptography library (pip install cryptography):

python -c "
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
import base64
sk = Ed25519PrivateKey.generate()
print('private:', base64.b64encode(sk.private_bytes_raw()).decode())
print('public:', base64.b64encode(sk.public_key().public_bytes_raw()).decode())
"

Node

Uses tweetnacl (npm install tweetnacl):

node -e "
const nacl = require('tweetnacl');
const kp = nacl.sign.keyPair();
console.log('private:', Buffer.from(kp.secretKey).toString('base64'));
console.log('public:', Buffer.from(kp.publicKey).toString('base64'));
"

Go

Uses the standard library crypto/ed25519 (no external dependencies):

cat <<'EOF' > genkey.go
package main

import (
    "crypto/ed25519"
    "crypto/rand"
    "encoding/base64"
    "fmt"
)

func main() {
    pub, priv, _ := ed25519.GenerateKey(rand.Reader)
    fmt.Println("private:", base64.StdEncoding.EncodeToString(priv))
    fmt.Println("public:", base64.StdEncoding.EncodeToString(pub))
}
EOF
go run genkey.go

Save the private key in a secrets manager. Treat it like a database credential.

Register the public key

Dashboard: at app.thegrid.ai/profile/api-keys, open the Trading keys section and paste the public key value.

Programmatic:

curl -sS -X POST "https://platform.api.thegrid.ai/v1/signing-keys" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"signing_key": {"label": "my-bot", "public_key": "BASE64_RAW_32_BYTE_PUBLIC_KEY"}}'

Requires keys:manage on the access token.

The response includes the fingerprint (SHA256 of the public key, base64-encoded without padding); send that fingerprint as x-thegrid-fingerprint on every signed Trading request.

Sign a request

The string you sign is the concatenation of:

1. Unix timestamp in seconds, as a string
2. HTTP method, uppercase (POST, GET, DELETE)
3. Request path only, excluding any query string (e.g., /v1/orders)
4. Request body as a string, or the empty string for GET and DELETE

Sign that string with your Ed25519 private key, then base64-encode the resulting signature. Send three headers on every Trading API request:

Header	Value
x-thegrid-signature	Base64-encoded Ed25519 signature of <timestamp><METHOD><path><body>.
x-thegrid-timestamp	Unix timestamp in seconds, as a string. Must be within 30 seconds of server time, otherwise the request is rejected with 401.
x-thegrid-fingerprint	SHA256 hash of your public key, base64-encoded without padding. The dashboard shows this value when you register the key.

For example, GET /v1/orders?status=filled signs /v1/orders, not /v1/orders?status=filled. Query filters are parsed after signature verification.

Trading private keys are base64-encoded raw Ed25519 seed or secret-key bytes, not PEM blocks. If your crypto library imports PEM by default, decode the raw base64 bytes directly instead.

If you see 401 on otherwise-correct requests, check your machine's clock first. Timestamp drift is the most common cause.

For a safe end-to-end auth check, use Diagnostics. Consumption diagnostics verifies a key without inference spend, Trading diagnostics reports timestamp drift and signing errors with server_time, and Platform diagnostics verifies OAuth/account readiness.

Key management

Keep keys out of your source tree. Use environment variables for Consumption keys, and a secrets manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, your CI/CD secret store) for Trading private keys.

export GRID_API_KEY="..."

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.thegrid.ai/v1",
    api_key=os.environ["GRID_API_KEY"],
)

Rotation

Rotate keys periodically and any time you suspect exposure:

1. Generate a new key in the dashboard.
2. Roll your application to use the new key.
3. Delete the old key from the dashboard.

The dashboard supports multiple active keys per account, so you can roll without downtime.

Compromised keys

Delete a compromised key in the dashboard immediately. It stops working at the API edge as soon as the deletion propagates. If you suspect billing impact, contact [e-mail] with the key fingerprint and approximate compromise window.

Where next

• Programmatic onboarding: OAuth login → keys → first API calls
• Platform API: OAuth, key CRUD, account settings
• Consumption API: endpoints that take Consumption keys
• Trading API: endpoints that take Trading keys
• Diagnostics: read-only auth and setup checks for all three API surfaces
• Errors and rate limits: what 401 looks like and how to debug it