Authentication

Every request needs an API key in the Authorization header:

curl --request GET \
  --url https://api.orbbit.co/v1/commodities \
  --header 'authorization: Bearer orbbit_data_YOUR_KEY'

A key is the text orbbit_data_ followed by 64 letters and digits. Keep it secret: anyone holding it can call the API as you.

Create a key

Sign in to the Orbbit console and open API Keys.
Click New Key.
Under Name, give the key a name you’ll recognize later, such as cost-dashboard-prod.
Under Spend budget (USD), set the most this key may spend in a month.
Under Scope, tick the endpoints the key may call. A key can only call the endpoints you tick.
Click Create, then copy the key from the Save your key window.

The console shows the full key only once. Orbbit stores a one-way fingerprint of it, not the key itself, so nobody — including Orbbit — can show it to you again. If you lose it, revoke it and create a new one.

The key list shows the last four characters of each key so you can tell them apart.

Choose what a key may call

Each endpoint needs its own permission, called a scope. Give each key only the scopes it needs: a leaked key that can only search stores can do far less harm than one that can call everything.

Scope	Lets the key call
`search-commodities`	`GET /v1/commodities`
`get-commodity-prices`	`GET /v1/commodities/prices`
`search-branded-foods`	`GET /v1/branded-foods` and `GET /v1/branded-foods/categories`
`get-branded-foods`	`GET /v1/branded-foods/{id}`
`search-stores`	`GET /v1/stores`
`get-store`	`GET /v1/stores/{id}`
`get-store-products`	`GET /v1/stores/{id}/products`
`get-store-collections`	`GET /v1/stores/{id}/collections`
`get-product`	`GET /v1/products/{id}`

The console labels each scope in plain words — get-commodity-prices shows as Get Commodity Prices. You can change a key’s name, budget, and scopes at any time from API Keys. The key itself stays the same.

When a key is refused

Status	`error.type`	Why	What to do
`401`	`unauthorized`	The header is missing or malformed, or the key is unknown or revoked.	Check the header reads `Bearer` followed by the full key.
`403`	`forbidden`	The key is valid but does not have this endpoint’s scope.	Add the scope to the key in the console.

403 — missing scope

{
  "error": {
    "type": "forbidden",
    "message": "This key is not scoped to get-commodity-prices"
  }
}

See Errors for every error the API returns.

Revoke a key

Open API Keys, find the key by its name and last four characters, and click Revoke. Requests using it are refused with 401 straight away. Revoking cannot be undone.

Keep keys safe

Call the API from your server, never from a browser or mobile app, where anyone can read the key.
Store keys in a secrets manager or environment variable, not in source code.
Use a separate key for each app and environment, so you can revoke one without breaking the others.

Getting Started

AI Agents

Market Data

Industry Data

Create a key

Choose what a key may call

When a key is refused

Revoke a key

Keep keys safe

​Create a key

​Choose what a key may call

​When a key is refused

​Revoke a key

​Keep keys safe

Create a key

Choose what a key may call

When a key is refused

Revoke a key

Keep keys safe