A service account is a Risk Cloud user created to be the identity for an automated integration. It has a Role, entitlements, and permission sets like any other user, but no person logs into it interactively. Service accounts keep integrations off of personal user accounts.
This article covers when to use a service account, how to provision one, and how to decide whether multiple integrations should share a single account or each have their own.
For the underlying permission model, see Roles and Permissions. For token storage, caching, and rotation, see API Token Best Practices.
Why Use a Service Account
Integration teams use service accounts for a few reasons.
The first is token interference. If an integration runs under a personal user’s credentials and that user generates a new token from another tool such as Postman, the integration’s token is invalidated. The integration recovers on its next 401, but the cause is hard to trace.
The second is lifecycle coupling. When a user leaves the company and their account is disabled, the tokens for that account are deleted. Any integration relying on those credentials breaks.
The third is third-party access. Risk Cloud clients often have an outside vendor or consultant build the integration. A service account dedicated to the integration gives that third party the credentials they need without granting them access to any employee’s personal account. When the engagement ends, rotating or disabling the service account contains the change to the integration itself.
A service account isolates the integration from any one person. The integration owns its credentials and its permissions.
Service Accounts Use the Same Permission Model
A service account does not skip any of the standard checks. The full permission model described in Roles and Permissions applies.
- The API access permission must be enabled on the account. A service account without API access enabled returns 401 on every call.
- Module entitlements apply. A service account without
BUILDcannot hit build endpoints. - Application entitlements apply. A service account with no Read or Edit on an Application sees nothing in it.
- Step permission sets apply. A service account with no Permission Set sees no Records.
Plan a service account’s permissions as carefully as you would for any other user.
Provisioning a Service Account
To set up a new service account for an integration:
- Create the service account user in the admin UI.
- Enable the API access permission on the account. Without this, no credentials generated for the account will work. It is a one-click toggle in the user’s settings and easy to overlook.
- Generate Client and Secret keys for the service account through the Access Key flow. These are the long-lived credentials the integration uses to generate access tokens. See API Token Best Practices for storage and rotation guidance.
- Create a Role for the integration. Name it for the integration, for example “Integration: Risk Sync.” A dedicated Role makes the integration’s permissions auditable in one place.
- Attach the module entitlements the integration needs to the Role. Most integrations need a small set.
- Attach a Step Permission Set that grants Read or Edit on exactly the Steps the integration reads from or writes to.
- Grant the service account Application Entitlements on the Applications the integration touches. Read or Edit depending on what the integration does.
- Grant Build Access only if the integration creates or modifies Workflow design. Most integrations operate only on Records and do not need Build Access.
- Grant the service account the Role. Avoid placing the service account in unrelated Roles. Extra Role membership leaks unintended permissions.
Common Permission Needs
The permissions a service account needs depend on what the integration does.
Read Records into a data warehouse. No module entitlement is needed. The gate is the Step Permission Set. Application Entitlement: Read. Step Permission Set: Read on the relevant Steps.
Create new Records from an external system. Module: RECORDS. Application Entitlement: Edit. Step Permission Set: Edit on the Origin Step.
Update existing Records. Module: RECORDS. Application Entitlement: Edit. Step Permission Set: Edit on each Step where Records are updated.
Bulk-import Records. Module: IMPORT. Application Entitlement: Edit. Step Permission Set: Edit on the Origin Step.
Read saved Table Reports. Module: TABLE_REPORTS_READ. Application Entitlement: Read. Step Permission Set: Read on every Step the report references.
Generate audit exports. Module: STATUS (and ADMIN if the export covers admin data). Application Entitlement: Read. Step Permission Set: Read on the relevant Steps.
Modify Application design. Module: BUILD. Application Entitlement: Edit. Build Access on each target Application. Step Permission Sets are not relevant for build endpoints.
One Account or Many
Token regeneration invalidates all prior tokens for that user. How service accounts are assigned to integrations decides how integrations affect each other when a token is regenerated.
Sharing One Service Account
One service account, one Client ID and Secret, one access token at a time. Every integration using this account shares the same token.
- When any integration regenerates the token, every other integration’s next call returns 401. If they all retry once on 401, they recover. If they don’t, you see a brief outage on each one.
- Token rotation has to be coordinated across every consumer of the account.
- Simpler to provision and audit.
This is acceptable when all integrations belong to the same team, share a code base, and implement the same retry pattern.
One Service Account per Integration
Each integration has its own service account, its own credentials, and an independent token lifecycle.
- Regenerating one integration’s token does not affect any other integration.
- Audit logs attribute each API call to a single integration.
- Permissions can be tailored per integration. A read-only export does not need Edit on anything.
- More accounts to provision, but the isolation is usually worth it.
This is the right default for any team running more than one or two production integrations.
Which Pattern to Choose
- A single integration: one dedicated service account.
- Multiple integrations from the same team and code base: one shared service account is acceptable.
- Multiple integrations across different teams or repositories: one service account per integration.
- A mix of read-only and read/write integrations: one service account per integration so permissions can be scoped independently.
- An integration that acts on behalf of specific human users: use those users’ credentials, not a service account.
Practices for Shared Service Accounts
If multiple integrations share one service account:
- Every integration must implement retry-once on a 401. Treat it as a deployment gate.
- Centralize token issuance. One process generates the token, writes it to a shared secret store, and the other integrations read it from there. Avoid having each integration generate a token independently.
- Do not generate tokens from developer machines or CI using the production service account’s credentials. A quick test can invalidate the running integrations.
- Document the integration ownership. An on-call engineer should be able to find out who depends on the account before rotating its Client Secret.
Least Privilege
The common provisioning mistake is granting a service account the ADMIN module entitlement during development to get past 403 errors. That works, but it makes audit trails meaningless and least privilege impossible.
Scope a service account’s permissions to the specific operations the integration performs. Anything beyond that list is risk without value.