API keys

The API keys screen is where you issue the credentials that scripts and other systems use to reach this organisation’s data on their own account rather than a person’s, and where you rotate, revoke and review them. Open it from Administration → Integrations → API keys.

The API keys screen, with the identities above the keys

A key reaches the product’s API. The API says where to start, and Authentication shows how an integration uses its key.

How keys work

Every key belongs to an identity (a service account), never to a person. The identity holds roles and site access exactly as a person does, and the key can never do more than its identity — it can only be narrowed. That is why the screen shows the identities first: reading a key’s scope without reading the identity behind it is reading half the answer. A key minted from a person’s account would keep working after they left; a key on an identity does not depend on anybody. A key is never sent on ordinary requests. Your integration trades it once for a session token that lasts fifteen minutes, and sends that token on its requests — so the same roles, site limits and audit trail apply to an integration as to somebody using the app. The How a key is used section at the bottom of the screen shows the two requests with this organisation’s address filled in. Reuse a token for its whole fifteen minutes: asking for a new one on every request is refused as a rate limit.

The header

Figure or button	What it means
Live	Keys that are live or expiring
identities	Machine identities in this organisation
expiring	Shown when some keys stop working within a fortnight. A yellow banner then suggests rotating them, because the old key keeps working through a grace window
never used	Shown when some live keys have never been traded for a token — usually an integration that was never finished
Roles and access	Opens Access, where you give an identity its roles and sites
New identity	Creates a machine identity. Needs the identity permission
Issue a key	Issues a key. Needs the issue permission, and at least one identity that is not suspended

If you can read the register but not issue keys, a notice says so: reading which credentials exist is an access review, while issuing one is closer to creating a user. If you cannot read it at all, the screen says Not yours to read.

What a key can act as

The machine identities in this organisation.

Column	What it shows
Identity	Its name, with its code underneath
What it is for	Its stated purpose, or nobody said
What it may do	Its roles and whether it reaches at every site or a number of sites. A red Nothing means it holds no role, so any key on it could do nothing. This is the ceiling on every key the identity carries
Acts as	Itself or A person (see below). Administrators see it as a button that switches between the two
Live keys	How many live keys it holds
State	In use or Suspended
(button)	Suspend stops every key the identity holds at once, including ones nobody remembers issuing. Restore lets them work again

Identities created by other parts of the product appear here too, such as the ones IT discovery’s agents and collectors report as.

Acting as itself, or as a person

Setting	Meaning
Itself	The default. Every request a key makes is answered against the identity’s own roles
A person	A key may ask on behalf of a named person, and the answer is narrowed to that person’s permissions too — never more than the person may do. Needed by anything that serves several different people

Switching back to Itself does not end tokens already traded; they keep their fifteen minutes. Revoke the key to end those.

Creating an identity

Field	What it means	Notes
Code	The identity’s permanent address, such as `stores-integration`	Required. Lower case letters, digits and hyphens, up to 60 characters. Cannot be changed afterwards
Name	What it is called on screens	Required. Up to 150 characters
What it is for	Its purpose	Optional, up to 300 characters, but it is the first question an access review asks and the one a code cannot answer
Roles	What the integration may do	Optional. Choose the roles that hold what the integration needs — a reader’s gateway needs a role that may post a reader’s messages. With none, a warning says it can do nothing and a key for it would be refused

Create it creates the identity. It gets an account of its own that can never sign in with a password. It starts acting as itself, with the roles you chose, and reaching every site (no site grants means every site, everywhere in this product). Narrow it to a site, or change its roles, on Access, then issue it a key here. The same form opens from Add a service account on Access, and makes the same thing: an identity made on either screen is offered under Acts as straight away.

The keys

Column	What it shows
Key	Its name, with its prefix underneath. The prefix identifies the key; it is not the key
Acts as	The identity it belongs to
Narrowed to	The first two permissions it is narrowed to and how many more, or everything the identity can do. A key issued from a reader’s own screen says Posts for one reader only, and one issued from a sensor feed says Publishes for one sensor feed only with the feed’s code
State	Live, Expiring (within a fortnight), Expired, Revoked (with the reason underneath) or Rotated
Stops	When it stops working
Last used	When it was last traded for a token, with how many times this week and how many were refused, or never
(buttons)	Rotate and Revoke

Issuing a key

The Issue a key dialog, with the scope picker grouped by module

Field	What it means	Notes
Acts as	The identity whose roles the key uses	Required. Lists identities that are not suspended. It is the ceiling: nothing below can raise it. If the identity holds no role, a red message says a key on it could do nothing
Name	What the key is for	Required, up to 150 characters, so somebody can tell two keys apart in a year
Stops working after	How many days the key lasts	Default 90. Between 1 and 365. There is no way to ask for a key that never expires
Narrow it to	Which permissions the key may use	Choose Acts as first — until then the list says so, because what a key can be narrowed to depends on what that identity may do. Only the permissions the identity’s roles hold are offered. Grouped by module. Tick individual permissions, or all of it for a whole module, which also covers permissions a later release adds to that module. Choosing nothing gives the key everything the identity can do. Whatever you tick, the key can never do more than its identity

Issue it creates the key and shows it once.

The key is shown once. Nothing in this product can read it back afterwards — not another administrator, not support. Put it where it is going before you close the dialog. A lost key is replaced, not recovered.

Rotating a key

Rotate issues a successor with the same name, identity and scope, and shows it once. Offered on keys that are not revoked, not already rotated and not expired.

Field	What it means	Notes
The old key keeps working for	The grace window, in days, before the old key stops	Default 7. Between 0 and 90. Zero ends it now, which is what to choose if the key has leaked. A window can only bring the old key’s expiry in, never push it past the date it already had; the dialog shows that date

There is no way to widen a key. Rotation carries the scope forward, and a wider key is a new key.

Revoking a key

The dialog names the key, its identity and when it was last used.

Field	What it means	Notes
Why	The reason for revoking	Required, up to 200 characters. Somebody will ask, months later, when an integration stops working

Revoke it stops the key being traded for a token at once, and stops any token already traded from writing anything; a read can finish out the token’s last few minutes. There is no undo — a replacement is a new key.

Finding the call behind a screen

Whoever builds an integration usually needs to know which call a screen makes — which call adds an asset, for instance. Turn on Developer mode in your profile and every screen gains an API button (Show the API behind this screen). It opens The API behind this screen, listing the Functions it calls and the Read models it reads, each described in the same words as the API reference, for the version your organisation is running. For a call that changes something, What to send writes an example request carrying every field the call accepts, required ones first, each with a placeholder of the right kind — a number, a yes or no, a text, or the identifier of a record together with where that identifier comes from. Copy the request copies it. Hide the rest trims the request back to the fields a create cannot proceed without, listing the others under And the ones it can do without. Developer mode is only offered to people whose role lets them view integrations, and it changes nothing about what they may read or write.

Who can manage this

Permission (as shown on Access)	Covers	Default roles
See api keys, their scopes and what they have been used for	Opening this screen and reading both lists	System Administrator, Auditor, Executive
Issue and rotate api keys	Issue a key and Rotate	System Administrator
Revoke api keys	Revoke	System Administrator
Create and suspend service accounts	New identity, Suspend and Restore, and switching Acts as	System Administrator

None of these is on the Maintenance Administrator’s default pattern: a credential that can reach the whole API is not maintenance configuration. See roles.

The API

What a key can reach, and where to start building with it.

Security events

Issuing a collector key that can follow the audit trail and nothing else.

Setting up

Configuration

How keys work

The header

What a key can act as

Acting as itself, or as a person

Creating an identity

The keys

Issuing a key

Rotating a key

Revoking a key

Finding the call behind a screen

Who can manage this

The API

Security events