Working with Service Accounts
Overview
A service account is an AttackForge user account that's used by a system rather than a person. Scanners, ticketing tools, CI/CD pipelines, reporting tools and AI agents use service accounts to connect to AttackForge through the Self-Service REST APIs, which authenticate with an API key.
Use a single account for one narrow job, a group when several integrations need the same access, and a blocked Admin account only when an integration needs data from across the whole system.
Why use a service account
Integrations keep working when people move on. If an integration uses a person's API key, it breaks when that person leaves or changes role. A service account belongs to the integration.
Least privilege. A service account only gets the API endpoints and data the integration needs, not everything a person can do.
A clear audit trail. Changes made by an integration are recorded against its own account, so they're easy to tell apart from changes made by people.
Easier key management. Each integration has its own key, so one key can be replaced without affecting anything else.
How API access works
Every API endpoint is disabled for every user by default, including Administrators. Access has to be granted endpoint by endpoint.
API access can be granted to users or to groups.
An API key can only reach the data its user can already access in AttackForge, such as the projects, vulnerabilities and asset libraries they've been given.
Who benefits
Who
How
Administrators
Control exactly what each integration can do, and switch it off in one place
Security and integration engineers
Connect tools to AttackForge without using their own credentials
Security and compliance teams
See which changes came from which integration, and show that access follows least privilege
Choose how to set up your service accounts
There are three ways to set up service accounts. Pick the one that suits how many integrations you have, and what data they need.
Option 1: single service account
Option 2: integrations group
Option 3: blocked Admin account
What it is
One account, with access to just the endpoints it needs
A group of non-admin service accounts, which share the group's endpoint and data access
An Admin account that can't sign in, with only the endpoints it needs opened
Data it can reach
The data the account has been given
The data objects linked to the group, such as projects and asset libraries
All data, because it's an Admin
Best for
One integration with a narrow job
Several integrations that need the same access
Integrations that need data across the whole system, such as reporting or user provisioning
Watch out for
Access has to be managed account by account
Every account in the group gets the group's access
The widest reach, so open as few endpoints as possible
Option 1: create a single service account
Create one service account with explicit access to the API endpoints needed for the task.
Create the service account user in the Users module.
Give it access to the data the integration needs, such as the right projects.
Open the user's Managing Access section and choose Self-Service RESTful API.
Grant access to only the endpoints the integration needs.
Generate the account's API key, and store it securely in the integration.

Option 2: use a group for your integrations
Create a group for your integrations, and manage endpoint and data access on the group instead of on each account.
Create a group, such as "Integrations". See Groups.
Create non-admin service accounts, and add them to the group.
Grant the group access to the specific API endpoints the integrations need.
Link the group to the data objects the integrations need, such as projects and asset libraries.
To add a new integration later, create a service account and add it to the group. It gets the group's access straight away.
Option 3: use an Admin account that can't sign in
Some integrations need data from across the whole of AttackForge. For these, use an Admin service account, block it from signing in, and open only the API endpoints it needs.
Create a service account user with the Admin role.
Grant access to only the API endpoints the integration needs.
Block the account from signing in: in the Users module, open the user then go to Account and choose Block User Sign In.
Unlike deleting a user, blocking an account's sign-in doesn't stop its API access. The integration can still use the API key, but nobody can sign in to AttackForge as that account.
Set up service accounts when you use SSO-only logins
If your organisation only allows sign-in through SSO, each service account would normally need to be linked to a real account in your Identity Provider. For service accounts that aren't linked to your Identity Provider:
Create the service account users with the Create User workflow, not Invite User. You can use any email address, because it doesn't need to be validated.
Temporarily turn on Local Account logins, so you can sign in as the service accounts and generate their API keys. Then turn Local Account logins off again straight away.
Block the service accounts from signing in.
The service accounts can then use their API keys, but no one can sign in with them.
Build custom API endpoints with HTTP-triggered Flows
If you need to create custom API endpoints, or don't want users calling the REST APIs directly, use HTTP-triggered Flows. A Flow gives the integration a single endpoint that does exactly one job, for example creating a vulnerability in a set format. The Flow runs as its owner, so the integration never needs a broad API key of its own.
See HTTP trigger authentication.
Look after your service accounts
Give each integration its own account and key, so a key can be replaced, or an integration switched off, without affecting the others.
Name accounts clearly, such as "svc-jira-sync", so everyone can tell they're not people.
Use a shared mailbox you control for the account's email address, so notices about the account aren't lost.
Store API keys in a secrets manager, or as secrets in Flows, never in code or shared documents.
Review access regularly. Remove endpoints the integration no longer uses.
Block or remove accounts for integrations that are retired.
Tips
Start with the fewest endpoints possible, and add more only when the integration needs them.
Prefer Option 1 or 2. Use an Admin service account only when the integration really needs data from across the whole system.
Test the key straight away with a simple read-only call, so you know access is set up correctly.
Write down what each service account is for, who owns it, and which systems hold its key.
FAQ
Do Administrators have API access by default? No. Every endpoint is disabled for every user by default, including Administrators.
If I block a service account from signing in, does its API key still work? Yes. Blocking stops anyone signing in to AttackForge as that account, but the API key still works.
Can a service account see vulnerability data it hasn't been given? No. A key can only reach the vulnerability data its user can already access in AttackForge.
Can I grant API access to a group instead of each account? Yes. Grant the group access to the endpoints, link it to the data, and add the service accounts to it.
We only use SSO. How do we create service accounts? Use Create User, temporarily turn on Local Account logins to generate the API keys, turn Local Account logins off again, then block the accounts from signing in.
Do API keys expire? The API key is static and doesn't expire, but a new one can be requested at any time.
Related pages
Last updated