API tokens and least privilege
An API token is a password for a program. Whoever holds it can do whatever the token allows, for as long as it exists. This page explains the two things that decide what a token allows, and the habits that keep a leaked or misused token from doing much harm. Creating tokens is covered in the REST API documentation.
Two things decide what a token can do
| Layer | What it controls | Set where |
|---|---|---|
| Abilities (V8.4.0+) | Which endpoints the token may call, as resource.read and resource.write pairs such as devices.read or snippets.write |
Chosen when the token is created |
| Owner’s role | Which records lists and lookups return | The role of the user who owns the token |
A call to an endpoint outside the token’s abilities is refused with 403 Forbidden and the message Invalid ability provided. A call inside them returns only the records the owner’s role can see, even if every ability is selected. The abilities table in the main docs lists each ability.
Abilities are the hard limit. Treat the owner’s role as a filter on what the token reads, and use abilities to decide what it can change: a token with no .write abilities can’t change anything, whatever its owner’s role.
One token per integration, owned by a service account
The pattern that follows from those two layers:
- Create a service account for each integration, or each group of related integrations, rather than using a person’s account. A person leaving or changing role then doesn’t break the integration, and the API activity is attributed to the integration, not a colleague.
- Give that account a role that covers only the devices the integration needs. A backup report for the branch estate doesn’t need to see the data centre.
- Create one token per integration with only the abilities it calls. Check each endpoint the code uses against the abilities table.
- Name the token after the integration (
ci-change-gate,servicenow-tickets), so you know what breaks when you revoke it.
| Integration | Abilities it needs |
|---|---|
| Backup coverage report | devices.read |
| CI/CD change gate | devices.read, configs.read, policycompliance.read |
| Device sync from your own source | devices.read, devices.write |
| Snippet deployment from a pipeline | snippets.write, plus the read abilities for the checks around it |
Writes deserve extra care
Read tokens can leak data. Write tokens can change your network:
snippets.writecan send configuration to devices.devices.writecan delete and disable devices.users.writecan create and change rConfig users.
Give write abilities only to integrations that need them, keep those integrations’ tokens in a secrets manager with tight access, and prefer a separate read-only token for everything else the same integration does.
Device credentials come back by default
The device endpoints return each device’s stored username and passwords unless rConfig is set to mask them (MASK_DEVICE_CREDENTIALS). A devices.read token can therefore read device credentials for every device its owner’s role can see.
- On v2 device calls, pass
with_credentials=falseso the response leaves out the username and passwords. - Ask your rConfig administrator whether
MASK_DEVICE_CREDENTIALSshould be turned on for your server, so passwords are never returned over the API.
Config text is a separate case: when config obfuscation is on, configs returned over the API are masked the same way as in the UI.
Storing, rotating and revoking
- Store tokens in a secrets manager (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, your CI system’s secret store). Never in code, a repository or a shared document.
- Send the token in the
apitokenheader, not the URL parameter. URLs end up in proxy and web server logs. - A token is shown once. If it’s lost, create a new one and revoke the old one.
- Rotate on a schedule and whenever someone with access to it leaves. Create the new token, switch the integration over, test it, then revoke the old one.
- Tokens created before V8.4.0 no longer work. They were not migrated. See re-issue tokens after upgrading.