Service accounts
The Service Accounts page (route /service-account-admin) manages the non-human identities that software and automation use to access the Agilicus API and your resources.
Purpose
A service account is a non-human identity that can use the Agilicus API or access resources without a user present. You would typically create a service account for a task performed without a person: a service running in a virtual machine or container can use a service account to represent the service, and a batch job that runs periodically can use a service account to access a resource. This page creates service accounts and lets you view, modify, and delete existing ones.
Why use it
- Let automation act on behalf of your organisation without storing a person’s credentials.
- Scope what each automated client may do, and revoke its access cleanly when the task is finished.
- Give software a stable identity that does not change when staff leave.
- Restrict a service account to specific sub-organisations.
When to use it
- When you deploy software that needs to call the Agilicus API (see API and automation).
- When a batch job or scheduled task needs to read or write resources.
- When a connector or integration needs its own identity rather than a human user’s.
Prerequisite: permission to administer service accounts (an owner or administrator role).
How to use it
- Open Access > Service Accounts from the left navigation.
- Review the table. Each row is a service account with its name, allowed sub-organisations, description, enabled state, and actions.
Creating a service account
- Select ADD SERVICE ACCOUNT. A new empty row appears at the top of the table.
- Type a Name (the only required field) and optionally a Description.
- Click outside the row to save. The service account is created asynchronously and the table reloads.
Editing and managing
- The name, description, and Enabled toggle are editable in place.
- Select the more menu on a row for the following actions:
- Download Authentication Document downloads a JSON document containing the service account’s credentials for use in scripts and integrations.
- Copy Service Account Email copies the service account’s email address to the clipboard.
- Configure Allowed sub-organisations opens the transfer-list dialog for restricting which sub-organisations the account can act in.
Fields and controls reference
| Control | Purpose | Required | Default | Valid values | Notes |
|---|---|---|---|---|---|
| Name | The service account’s name | Yes | n/a | Any text | Unique per organisation |
| Allowed sub-organisations | Which sub-organisations the account may act in | No | All | One or more sub-organisations | Managed through the transfer-list dialog |
| Description | Free-form note about the account | No | n/a | Any text | |
| Enabled | Whether the account may authenticate | No | Enabled | On or off | |
| ADD SERVICE ACCOUNT | Adds a new editable row | n/a | n/a | n/a | |
| DELETE SERVICE ACCOUNTS | Deletes the selected accounts | n/a | n/a | n/a | Bulk action on ticked rows |
| REVOKE SESSIONS | Ends the selected accounts’ active sessions | n/a | n/a | n/a |
Dialogs and popups
- Configure Allowed sub-organisations: the transfer-list dialog for selecting which sub-organisations the account may use.
- Confirmation dialogs: deleting service accounts and revoking sessions confirm before acting.
Configuration versus diagnostics versus confirmation
- Configuration: names, descriptions, enabled state, allowed sub-organisations, and the authentication document.
- Diagnostics: none on this screen; audit records for service account activity appear in Audits.
- Confirmation: deleting a service account is permanent and breaks any automation using it. The authentication document is a credential: treat it like a password and rotate it if it may have leaked.
Pagination and async behaviour
- The table pages at 25 rows per page.
- Service account changes apply asynchronously. After creating, editing, or deleting an account, wait a few seconds and reload to confirm.
Troubleshooting
- Automation fails to authenticate: download the authentication document again and check the account is Enabled. Confirm the account’s allowed sub-organisations include the organisation the client is acting in.
- A client’s session is compromised: use REVOKE SESSIONS on the account, then rotate its authentication document.