Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

  1. Create the service account user in the Users module.

  2. Give it access to the data the integration needs, such as the right projects.

  3. Open the user's Managing Access section and choose Self-Service RESTful API.

  4. Grant access to only the endpoints the integration needs.

  5. 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.

  1. Create a group, such as "Integrations". See Groups.

  2. Create non-admin service accounts, and add them to the group.

  3. Grant the group access to the specific API endpoints the integrations need.

  4. 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.

  1. Create a service account user with the Admin role.

  2. Grant access to only the API endpoints the integration needs.

  3. 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.

Important: Because this account is an Admin, its API key can reach data across the whole system through any endpoint it has access to. Open as few endpoints as possible, and protect the key carefully.

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:

  1. 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.

  2. 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.

  3. 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.

Last updated