GroundRoute
Sign inGet API key

Authentication

Every request to the GroundRoute API authenticates with an API key sent as a Bearer token.

API keys

  • Keys look like gr_live_….
  • The plaintext key is shown once, at creation. GroundRoute stores only its SHA-256 hash — the raw key is never logged and can never be retrieved again. Store it in a secret manager.
  • A key is scoped to one tenant. It carries the tenant's plan, BYOK status, and spend policy, all resolved server-side. You cannot set tenant_id from a request body — it is always derived from the key.

The Bearer header

Send the key on every request:

Authorization: Bearer gr_live_xxxxxxxxxxxxxxxxxxxx

curl -s https://api.groundroute.ai/v1/search \
  -H "Authorization: Bearer $GROUNDROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "hello world"}'

A missing, malformed, unknown, inactive, or revoked key returns 401 with an error envelope of type auth.

The same key works for the REST API, the MCP server, and the OpenAI/Tavily-compatible shim.

Managing keys (console)

Key management is done from the console under your tenant. All operations are tenant-scoped — a key from another tenant is indistinguishable from one that does not exist (you get 404).

Create

POST /console/keys with an optional name. Returns the plaintext key once:

{
  "id": "…",
  "api_key": "gr_live_…",   // shown once — store it now
  "key_prefix": "gr_live…XYZ9",
  "name": "production"
}

List (masked)

GET /console/keys returns metadata only — never the key. Each entry has id, key_prefix (a masked display prefix), name, status, created_at, and last_used_at.

Rotate

POST /console/keys/{key_id}/rotate revokes the old key and issues a new one in a single step, returning the new plaintext key once. The revoked key's cached auth context is purged immediately, so it stops working right away — not after a TTL.

Revoke

DELETE /console/keys/{key_id} revokes the key immediately. As with rotation, the revoked key's auth cache is purged so it stops authenticating at once.

Console sessions vs API keys

The console (human login: signup, login, password reset) uses a separate session-cookie credential. API keys authenticate the /v1 data plane and MCP; console sessions authenticate the management endpoints under /console and /v1/console. They are different credentials on different surfaces.

PreviousQuickstartNextSearch API