Skip to content
Guides & References

API tokens and least privilege

How rConfig REST API tokens are scoped by abilities and by their owner's role, and how to give each integration only the access it needs.

API & DeveloperUpdated
On this page

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:

  1. 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.
  2. 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.
  3. Create one token per integration with only the abilities it calls. Check each endpoint the code uses against the abilities table.
  4. 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.write can send configuration to devices.
  • devices.write can delete and disable devices.
  • users.write can 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=false so the response leaves out the username and passwords.
  • Ask your rConfig administrator whether MASK_DEVICE_CREDENTIALS should 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 apitoken header, 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.

Type to search.