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 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.
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.
To change a key's role, open the row's … menu and select Change role …. The new role applies within a minute.
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.
Open the row's … menu and select Rotate ….
Choose when the old key expires: At once, After 24 hours or After 7 days (recommended).
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.
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.
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.
