Authentication and keys

Get a key

Keys come with a plan. In this order:

• Create an account in the console, or sign in with your Gloom account, and confirm your email.
• Choose a plan under Billing. Checkout runs on Stripe, and the plan starts once Stripe confirms the payment.
• Create a key under Keys. It is shown once, so copy it then: Gloom stores only a hash and cannot show it again. A lost key is revoked and replaced.

Without a plan, creating a key is refused with 402.

Send the key

Either header works. When both are sent, Authorization is read first.

curl https://api.gloom.sh/v1/macro/cpi -H "Authorization: Bearer gds_..."
curl https://api.gloom.sh/v1/macro/cpi -H "x-api-key: gds_..."

Keep keys on a server or in a script, never in a web page.

Key format

Gloom Datasets keys start with gds_. The Gloom API answers on the same host, but its keys are different keys for different APIs: a Gloom Pro key (gloom_mcp_) or News API key (gloom_news_) gets 401 wrong_key on a dataset route, and a gds_ key is refused with 401 on the Gloom API's routes. Anything else gets 401 invalid_key.

What a key reads

A key carries its account's plan. Keys have no scopes of their own: every key on an account reads the same datasets and spends from the same credits.

• The account needs a plan. Without one, for example after a plan ends, every key gets 402 plan_required.
• The account needs a verified email. Until then its keys get 403 key_disabled.
• A revoked key gets 401 invalid_key.
• How many keys an account holds depends on the plan: