API & Developer guides

These guides cover driving rConfig from other systems: scripts, pipelines, portals and integrations that read from rConfig or change it. They explain which extension point fits which job, how REST API access is scoped, and where the edges are. The step-by-step procedures stay in the REST API documentation; these pages explain the design behind it.

Four ways to extend rConfig

The developer docs describe four ways to extend rConfig. They differ in who builds them and where the code runs.

Mechanism	What it is	Who builds it	Runs
REST API	HTTP and JSON access to devices, configs, compliance results, tasks, users and more	Your team	Outside rConfig, in any language
Script Integration Engine	Scripts that collect configs from devices the built-in connections can’t reach	Your team	On the rConfig server
Custom Commands	Laravel Artisan commands with direct access to rConfig’s models and services	rConfig Professional Services only	Inside the rConfig application
Custom Workflows	Multi-step service automation for ISPs and MSPs, such as site provisioning	rConfig Professional Services	Inside rConfig, combining native automation with SIE script logic

The REST API is the only one of these you build and run entirely outside rConfig, so it is the usual starting point. Reach for the others when the work has to happen inside rConfig: SIE when the problem is collecting from an awkward device, and Professional Services when the integration needs deep access to rConfig’s internals. The Custom Commands page is explicit that only commands developed by Professional Services should be installed in production.

The Script Integration Engine guides cover SIE in depth.

How REST API access is scoped

The REST API is available with Professional and Enterprise licences. Every request carries a token, and two things decide what that token can do.

Layer	What it controls	Set where
Abilities (V8.4.0+)	Which endpoints the token may call, as `resource.read` or `resource.write` pairs such as `devices.read` or `configs.read`	Chosen when the token is created
Owner’s role	Which records the token can see within those endpoints	The role of the user who owns the token

A call outside the token’s abilities returns 403 Forbidden. A call inside them still returns only the records the owner’s role can see, even if every ability is selected. The practical pattern follows from that: a dedicated service account whose role covers just the devices the integration needs, and one token per integration with only the abilities it uses. The abilities table lists each ability and what it grants.

Three details catch people out:

The token goes in the apitoken header (or URL parameter). An Authorization: Bearer header is refused with 401.
Tokens created before V8.4.0 were not migrated. Integrations using them need a new token after the upgrade.
A token is shown once, at creation. Store it in a secrets manager, not in code.

v1, v2 and the OpenAPI specification

The API is a mix of v1 and v2. The docs recommend v2 for new integrations and v1 when you need resources that only exist there, such as tasks, snippets, templates or device credentials. The OpenAPI page has the coverage table for each version.

rConfig describes its own API in three forms, all generated from the routes and validation rules of your install:

Form	Audience	Notes
In-app documentation	People	Under Settings in rConfig, with request and response examples
OpenAPI 3.0 specification	Postman, Insomnia, Swagger UI, client generators	Written to disk on the server, never served over a URL
AI-Agent REST API Docs	AI coding agents	Markdown rendered from the same specification

The generated files reflect the API at the moment they were built, so regenerate them after every upgrade. They also record few response bodies, because generation never calls the live API; send a test request to see the real shape.

REST API or MCP?

rConfig also runs an MCP server for AI agents. It overlaps with the REST API on reading data, but the two are built for different callers.

	REST API	MCP server
Caller	Your code: scripts, pipelines, portals	An AI agent acting on a plain-language request
Access	Read and write, limited by token abilities	Read-only, eight tools
Authentication	REST API token in the `apitoken` header	MCP token as a bearer token
Scope	Records the token owner’s role can see	Devices the token owner’s role can see

The tokens are separate: an MCP token only works on the MCP endpoint, and a REST API token can’t be used for MCP. Use the REST API when you are writing the integration and know which calls it makes. Use MCP when an engineer wants an agent to answer questions from rConfig data alongside other tools. The Iris guides cover the agent side.

An agent can also write code against the REST API. That is what the AI-Agent REST API Docs are for, and the calls the generated code makes are still bound by the token you give it.

Automation versus collection

API Collections is easy to confuse with the REST API, but it runs the other way. With API Collections, rConfig is the client: it calls a cloud platform, controller or SaaS service and stores the response as a versioned config. Use it when the thing you want to back up has a REST API. Use the REST API when another system wants to drive rConfig.