--- title: "API keys" description: "Create, rotate, re-role and delete the API keys of your organisation and of your carriers in Orbit MissionControl, and see each key's history." url: "https://support.pr-9.orbit.do/en/advanced-features/api-keys" locale: "en" apps: ["mission"] lastReviewed: "2026-10-21" --- # API keys Create, rotate, re-role and delete the API keys of your organisation and of your carriers in Orbit MissionControl, and see each key's history. An API key lets another system work with Orbit without a person signing in: your TMS or ERP through the Operator API, or a carrier's telematics through the Carrier API. You manage every key of your organisation and of your carriers in Orbit MissionControl under **Settings** > **API-Keys**. **Key highlights:** * **Two kinds of key:** **Operator keys** open the Operator API for your whole organisation. **Carrier keys** belong to one carrier and see only that carrier's tours. * **Shown once:** Orbit stores only a fingerprint of a key. You see the key itself once, right after you create or rotate it. After that the list shows only its beginning and its last four characters, for example `orb_car_live_…7Fq2`. * **A role per key:** each key holds a role, which you choose when you create it and can change later. * **Rotation without downtime:** rotating creates a new key, and the old one keeps working for an overlap you choose. ## The list The page opens with **Operator keys**. Select **Carrier keys** to see the keys of your carriers, with a **Carrier** column. The search box at the right finds keys by name; in **Carrier keys** it also offers carriers, so you can narrow the list to one or more of them. Each row shows the key's name, its role, the end of the key, when it was last used and when it expires. A row can carry these markers: | Marker | Meaning | | ------------------------ | ---------------------------------------------------------------------------------------------- | | **Rotation recommended** | A key from before Orbit stored keys as fingerprints. It keeps working; rotate it when you can. | | **In 5 days** | The key expires in fewer than seven days. | | **Expires on 20.10.** | The old key of a rotation, working until that date. | | **Expired** | The key no longer works. The row is greyed out. | | **Deactivated** | The carrier is deactivated. The Carrier API refuses its keys until it is active again. | **Last used** is updated at most every 15 minutes, so a key in constant use can show a time a few minutes ago. ## Create a key 1. Open **Settings** > **API-Keys** and select **Operator keys** or **Carrier keys**, depending on the key you need. 2. Select **Create API-Key**. A card opens above the list. 3. Enter a **Name** that tells you where the key is used, for example `Telematics Northern Light`. For a carrier key, choose the **Carrier**. 4. Choose the **Role** and when the key **Expires**: **Never**, **In 30 days**, **In 90 days** or **In 365 days**. 5. Select **Create**. A dialog shows the key. Copy it with **Copy** and store it where the other system can read it, then select **I have saved the key**. > **Warning:** The dialog is the only place the key is shown. If you close it without saving the key, delete the key and create a new one. ![The API keys page in Orbit MissionControl with the Carrier keys view, a carrier chosen in the search box, and two keys of that carrier](https://support.pr-9.orbit.do/images/api-keys/carrier-keys.png) *The carrier keys of one carrier: the new key of a rotation above the old one, which still works until its expiry date.* ## Roles The role decides what a key may do. **Role** offers the roles a key of that kind can hold: * **Operator API Key Full Access** and **Operator API Key Read Only** for operator keys, **Carrier API Key Full Access** and **Carrier API Key Read Only** for carrier keys. These roles are only for API keys and grow with new features. * Your own roles under **Own roles**, when they are meant for the same kind of user and contain no condition that names a single user or team. You create them under **Settings** > **Roles**; see [Roles and Permissions](https://support.pr-9.orbit.do/en/advanced-features/roles-and-permissions). To change a key's role, open the row's **…** menu and select **Change role …**. The new role applies within a minute. ## Rotate a key Rotating replaces a key with a new one that has the same name and role. Use it when a key may have been seen by someone else, or regularly as a precaution. 1. Open the row's **…** menu and select **Rotate …**. 2. Choose when the old key expires: **At once**, **After 24 hours** or **After 7 days (recommended)**. 3. Select **Rotate**. The new key is shown once, as after a create. Enter it in the other system before the old one expires. The list then shows the new key and, below it, the old one with its expiry date. A key can be rotated once; to replace it again, rotate the new key. An expired key cannot be rotated. ## Delete a key Open the row's **…** menu, select **Delete …** and confirm with **Delete**. Systems using the key lose access within a minute. A deleted key cannot be restored. ## History Select **History** in a row's **…** menu to see what happened to a key: when it was created, rotated, re-roled or deleted, and by whom. The history of a rotated key also lists the keys it replaced, back to the first one. ## Example Spaceport Shipping Co. connects its warehouse system in Lyon with an operator key that never expires. Its carrier Northern Light Transport gets a carrier key with **Carrier API Key Read Only**, so its telematics in Hamburg can read its tours. When Julia, who set up the telematics, leaves the company, Max rotates the carrier key with an overlap of 24 hours and sends the new key to the carrier. ## Technical details Operator keys work with the Orbit API; see the [Orbit API Reference](https://orbit-api.readme.io/). Send the key in the `x-api-key` header. **Q: Can I see a key again after closing the dialog?** No. Orbit stores only a fingerprint of each key, so nobody can show it again. Rotate the key or create a new one. **Q: What happens to a key when the person who created it leaves?** Nothing. A key belongs to your organisation or to the carrier, not to a person, and keeps working. **Q: Why does a key still work right after I deleted it or changed its role?** Orbit remembers a key for up to a minute. After that every request uses the new state. **Q: What happens to a carrier's keys when I deactivate the carrier?** The Carrier API refuses them while the carrier is deactivated. The list marks them with **Deactivated**.