Service users overview

A service user is an identity for a system rather than a person: an integration, an automation, a script or a back-end job that needs to work with your organization’s data through the BreezeAuth API. For example, the system that keeps your HR platform and BreezeAuth in sync, or a nightly job that exports your audit logs.

Service users live in your organization next to your people, under Users › Service Users. Like any user, each one has an administrative role that defines what it can do. Unlike people, they have no e-mail address or password, can’t sign in to the admin console or to applications, and authenticate only with credentials.

Why use a service user

It’s tempting to let an integration use the account of the person who set it up. Service users avoid the problems that come with that:

• Integrations don’t depend on a person. When someone changes teams or leaves the company and their account is removed, integrations that used it would break. A service user belongs to the organization, not to a person.
• Only the access the integration needs. Each service user has its own role, usually much narrower than the role of the administrator who configures it.
• No passwords to share, no MFA prompts. Integrations authenticate with a client ID and a client secret designed for machines, and never need to answer a multi-factor authentication challenge.
• Clear audit trail. Actions appear in the Audit Logs under the service user’s name, so you always know which integration did what.
• Revoke one integration without affecting others. Deactivating a service user, or one of its credentials, stops that integration only.

Service users compared to people

	People (human users)	Service users
Represents	A person	A system: integration, automation, script
Signs in with	E-mail and password, passkeys, single sign-on	Credentials (client ID and client secret) only
Multi-factor authentication	Yes	Not applicable
Admin console	Yes, depending on their role	No
Uses the BreezeAuth API	Through the admin console	Directly, with access tokens
Administrative role	Any, including Owner	Any except Owner
Groups and applications	Can be added to groups and assigned to applications	Can’t be added to groups or assigned to applications

How it works

1. Create a service userGive it a name and the role your integration needs.
2. Create a credentialYou get a client ID and a client secret. The secret is shown only once.
3. Request an access tokenThe integration sends its credential to /oauth/token and gets a short-lived token.
4. Call the APIThe integration sends the token with each request. When it expires, it requests a new one.

Typical uses

• Provisioning. A system such as an HR platform or another directory creates, updates and removes users and groups in BreezeAuth. The SCIM Provisioner role is designed for this. See SCIM provisioning.
• Reacting to webhooks. When a webhook tells your system that something changed, a service user reads the details from the API.
• Reporting and compliance. A scheduled job exports audit logs or lists users and their access. The Auditor role gives read-only access.
• Internal tools. Back-office scripts that automate routine administration tasks.

In this section

• Create and manage service users: create them, choose a role, deactivate and delete.
• Credentials: create, rotate, deactivate and delete the credentials of a service user.
• Access tokens: exchange a credential for a token and call the API (technical).
• Restrictions and security: limit what service users can do and where they can connect from.