# API keys and organisations

> How organisations, satellites and their spaces, shops, brands and locations relate, which keys and tokens each satellite issues, who can create them and how to send them.

Source: https://docs.bifrostorbit.com/orbit/developers/api-keys-and-organisations/

Every key in Bifröst Orbit belongs to one satellite and, inside it, to one organisation or one part of it. A key from CMS Orbit never works in Commerce Orbit, and a key for Northwilds' Oslo shop never reads the Bergen shop.

## Organisations

An organisation is a company using Bifröst Orbit. Orbit keeps:

- **Its id:** 24 hexadecimal characters, such as `6650c0ffee0000000000abcd`. It is in the address of every screen, such as `/cms/o/6650c0ffee0000000000abcd`, and in every event as `tenant.organisationId`.
- **Its short name:** lowercase letters, digits and hyphens, such as `northwilds`, used in its sign-in address `app.bifrostorbit.com/signin/northwilds`.
- **Its members:** each with an Orbit role (Owner, Admin or Member) and the satellites they may open.

Satellites read who belongs to an organisation from Orbit. Owners and Admins in Orbit are admins in each satellite they open; Members start with the satellite's least access, and each satellite can give them more. There is no API for organisations or members.

## Inside each satellite

| Satellite | An organisation holds | A key belongs to |
| --- | --- | --- |
| CMS Orbit | Spaces, each with environments such as Production and Staging, and regions | One space and environment, optionally limited to some regions and languages |
| Careers Orbit | One career site | The organisation |
| Commerce Orbit | Shops | One shop |
| Travel Orbit | Brands | One brand |
| Booking Orbit | Locations | One location |
| Presence Orbit | Locations | The organisation |
| Insights Orbit | Sites | The organisation |

## Keys and tokens

| Satellite | Key or token | Starts with | What it can do | Who creates it, and where |
| --- | --- | --- | --- | --- |
| CMS Orbit | Public key | `cms_pk_` | Read published content | Developer, Admin or Owner, under **API keys** in the space |
| CMS Orbit | Secret key | `cms_sk_` | Also read drafts. Not on Production environments | as above |
| CMS Orbit | Management token | `cms_mt_` | Use the management API, optionally read-only. Lasts 1 to 365 days | Developer, Admin or Owner, under **Management tokens** |
| CMS Orbit | Agent key | `cms_ag_` | Connect an AI agent to the MCP server | On the **AI agents** screen in the space |
| Careers Orbit | Public key | `careers_pk_` | Read jobs and take applications | Admin, under **API keys** |
| Careers Orbit | Management token | `careers_mt_` | Use the management API, optionally read-only. Growth and Enterprise plans | Admin, under **API keys** |
| Commerce Orbit | Public key | `com_pk_` | Count your storefront requests | Admin, under **API keys** in the shop |
| Commerce Orbit | Secret key | `com_sk_` | Also read draft products. From a server only | as above |
| Travel Orbit | Public and secret keys | `trv_pk_`, `trv_sk_` | As in Commerce Orbit, for one brand | Admin, under **API keys** in the brand |
| Presence Orbit | Public and secret keys | `pre_pk_`, `pre_sk_` | A secret key can send review requests from your systems. Growth plan | Admin, under **API keys** |
| Insights Orbit | API key | `ins_live_` | Send events from your servers, read raw events through the API and GraphQL, or both. Reading needs Growth or above | Admin, under **API keys** |

Booking Orbit's public API needs no key: it is addressed by the location's booking name, and the location's **Allowed websites** decide which websites may call it from a browser.

Some things need no key at all: Travel and Commerce Orbit's catalogue reads, the Insights script and the Presence review widget.

Each satellite's developer docs describe its keys in full, such as [CMS Orbit's security and access](https://docs.bifrostorbit.com/cms/developers/security-and-access/), [Careers Orbit's API keys](https://docs.bifrostorbit.com/careers/developers/api-keys/) and [Commerce Orbit's API keys](https://docs.bifrostorbit.com/commerce/developers/api-keys/).

## Send a key

Send it in the `Authorization` header:

```http
Authorization: Bearer cms_pk_…
```

Every satellite also accepts `X-Api-Key: …`. CMS Orbit lets a public `cms_pk_` key go in the address as `?apiKey=`, and Careers Orbit a `careers_pk_` key as `?key=`, so answers can be cached close to your visitors. Never put a secret, preview or management key in an address or in a browser.

## Keep keys safe

- A key is shown once, when it is made. The satellite keeps only a hash of it, so nobody can show it to you again. Lost keys are replaced, not recovered.
- Use one key per website or system, named after it, such as northwilds.com. Then you can replace one without touching the others.
- Keep keys in your server's environment, not in your code.
- Give a key an expiry date where the satellite offers one, and revoke keys you no longer use.
- Where a satellite has **Allowed websites**, list the websites that may call it from a browser.

## AI assistants and the Orbit app

AI assistants don't use keys. They sign in with OAuth as a person on the team, and get a token for one satellite. See [Sign in with Orbit](https://docs.bifrostorbit.com/orbit/developers/sign-in-with-orbit/).
