#Authentication

The GPT-GOB API uses bearer token authentication. Every request must include your API key in the Authorization header.

http

Authorization: Bearer gob-live-x4f9k3m2nQ8wHvL7pYrJ5tA1cBdE6fG2sK9oXz0aPq

##API key formats

Keys come in two flavors. Both are 50–60 characters long after the prefix.

Prefix	Environment	Notes
`gob-live-`	Production	Real billing, real rate limits
`gob-test-`	Test mode	Free, capped at 100 RPM, no billing

##Creating a key

01.Sign in to the Console
02.Open Settings → API Keys
03.Click Create new key
04.Optionally restrict it to specific scopes (chat.read, chat.write, grs.score, embeddings)
05.Copy it immediately — you won't see it again

##Rotating keys

Keys can be rotated at any time without downtime. Old keys remain valid for 24 hours after rotation, giving you a window to roll out the new one.

bash

curl -X POST https://api.gpt-gob.ai/v1/keys/rotate \
  -H "Authorization: Bearer $GOB_API_KEY"

##Scopes

Scope	Allows
`chat.read`	Read chat history (Cave Memory)
`chat.write`	Create chat completions
`embeddings`	Generate embeddings
`grs.score`	Score arbitrary text against the Goblin Reward Signal
`models.list`	Enumerate available models
`usage.read`	Query usage and billing endpoints
`*`	All of the above (default for new keys)

##Errors

If authentication fails, you'll get a 401 with one of these error codes:

json

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "the cave doesn't recognize that key. check your spelling, tall one."
  }
}

Code	Meaning
`invalid_api_key`	Key is malformed or doesn't exist
`expired_api_key`	Key was rotated > 24h ago
`revoked_api_key`	Key was manually revoked
`scope_required`	Key lacks the required scope
`wrong_password_to_cave`	Auth header missing or malformed

##Best practices

▸Never expose keys client-side. Always proxy through your own backend.
▸Use scoped keys. Don't use a * key when chat.write is enough.
▸Set up an allowlist. In Console → Settings, restrict keys to specific IPs.
▸Rotate quarterly. Even if nothing leaked, rotate at least every 90 days.
▸Use `gob-test-` keys in CI. They're free and don't count against quota.