Navigation

10.27. Give Integrations and AI Agents Their Own Identity with Service Principals

Create service principals so scripts, integrations, and AI agents use their own roles, API keys, and rate limits instead of a technician's account.

10.27. Give Integrations and AI Agents Their Own Identity with Service Principals
Create service principals so scripts, integrations, and AI agents use their own roles, API keys, and rate limits instead of a technician's account.
10. SettingsUpdated: 11/19/2026

Most MSPs connect something to their PSA that is not a person: a reporting script, an RMM or documentation sync, a billing export, or an AI agent. The common shortcut is to issue that tool an API key from an administrator's account. It works until the administrator leaves, changes role, or turns on stricter sign-in rules, and in the meantime every change the tool makes looks as if that person made it.

A service principal is a non-human identity for that kind of tool. It has its own roles, its own API keys, and its own rate limit, and its work is labelled with its own name. Your team can see at a glance which changes came from the nightly sync and which came from a technician.

Availability: Service principals are an Enterprise Edition feature on the Pro plan. They are not shown in Community Edition. Below Pro, "API and MCP access for service principals is blocked immediately below Pro. Existing records remain available for cleanup." so you can still deactivate or delete them.

Open Settings > Security, then the Service principals tab. The page describes them as "Non-human identities with their own roles and API keys for integrations and agents."


Limits and seats

ItemDefault
Active service principals10. The header shows the count, for example 3 of 10 service principals.
Seats"Service principals do not consume seats."
MCP agentsMCP agents are service principals too, so they count toward the same limit.
Rate limitA burst of 120 requests, refilling at 60 requests per minute. This default is also the maximum an override may set.

When the limit is reached, "You have reached your limit of 10 active service principals. Deactivate or delete one to add another." On a self-hosted appliance, the limit comes from your license. The Service principals usage row also appears on your license and plan page.


Create a service principal

  1. Select New service principal.
  2. Enter a Name that says what the tool is, for example Nightly Hudu Sync or Finance Power BI Export, and a Description with the owner and purpose.
  3. Choose Roles. Give the principal only what its job requires. A reporting export needs read access to tickets, time, and invoices, not permission to delete clients.
  4. Leave Allow acting on behalf of a user off unless the tool must perform work as a specific person (see below).
  5. Optionally set a Rate limit override: Burst size and Requests per minute, each up to the default maximum. Enter both values or leave both empty.
  6. Select Save.

The list shows each principal's Name, Type (API or MCP agent), Act-as, Status, Roles, Active keys, Last used, and Created by.


Issue and rotate API keys

Select Keys on a row to open API keys for the principal.

  1. Enter a Key description such as Production server, issued Nov 2026 and select Create key.
  2. Copy the key from API Key Generated with Copy to Clipboard or Download as .txt. "Please copy your API key now. For security reasons, it will not be shown again."
  3. Configure the key in the tool.

To replace a key, select Rotate. A new key is issued and "The previous key keeps working for 5 more minutes so you can switch over." Update the tool within that window.

To cut a tool off, select Revoke. "Anything using this key stops working immediately."

The key list shows Status, Last used, and Expires for each key, so a key that has not been used for months is easy to spot. Service principal keys also appear on the API Keys tab, labelled with the principal they belong to.


Let a principal act on behalf of a user

Some tools perform work that should be credited to a real person. A ticket triage agent, for example, might add a comment that should appear under the technician who approved it. With Allow acting on behalf of a user turned on, a request can name an active internal user in the X-Alga-Act-As header (the user's ID).

Each action must be allowed for both the principal and that user. A principal cannot use act-as to reach anything the named user could not do, and a user cannot gain the principal's permissions.

Some actions must always be performed by a person. A principal without act-as receives an error asking it to send X-Alga-Act-As with an active internal user.


See what a principal did

  • Ticket comments written by a service principal carry a Service badge.
  • Work done on behalf of a user shows via and the principal's name, for example Alex Rivera via Ticket Triage Agent.
  • Last used on the principal and on each key shows whether the tool is still running.

Deactivate or delete a principal

Select Deactivate to pause a principal without losing its setup. Its keys stop working until it is reactivated, and it no longer counts toward the active limit.

Select Delete when the tool is retired. "Its API keys stop working. If it has history it is archived rather than removed." An archived principal keeps its name on past activity, so old comments and changes still show who made them.


Related guides