> For the complete documentation index, see [llms.txt](https://support.attackforge.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.attackforge.com/app/automations-and-integrations/working-with-service-accounts.md).

# Working with Service Accounts

## Overview <a href="#overview" id="overview"></a>

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](https://docs.attackforge.com/rest-api/pages/getting-started), 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.

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2F9NPe9dyqx8YBGVzMzvry%2Fservice-accounts-at-a-glance.svg?alt=media&amp;token=2340933a-479c-443a-a478-d9cb16fa2f23" alt=""><figcaption></figcaption></figure>

## Why use a service account <a href="#why-use-a-service-account" id="why-use-a-service-account"></a>

* **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 <a href="#how-api-access-works" id="how-api-access-works"></a>

* 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 <a href="#who-benefits" id="who-benefits"></a>

| 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 <a href="#choose-how-to-set-up-your-service-accounts" id="choose-how-to-set-up-your-service-accounts"></a>

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 <a href="#option-1-create-a-single-service-account" id="option-1-create-a-single-service-account"></a>

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](https://support.attackforge.com/app/modules/self-service-restful-api), and store it securely in the integration.

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FAx5hO2x6MLURnIs6uEQO%2FScreenshot%202026-11-04%20at%207.21.23%E2%80%AFam.png?alt=media&amp;token=c4fdf2ba-8cdc-4a59-b83e-0a2663dae170" alt=""><figcaption></figcaption></figure>

## Option 2: use a group for your integrations <a href="#option-2-use-a-group-for-your-integrations" id="option-2-use-a-group-for-your-integrations"></a>

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](https://support.attackforge.com/app/modules/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.
5. [Generate an API key for each service account](https://support.attackforge.com/app/modules/self-service-restful-api).

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 <a href="#option-3-use-an-admin-account-that-cant-sign-in" id="option-3-use-an-admin-account-that-cant-sign-in"></a>

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. [Generate the API key](https://support.attackforge.com/app/modules/self-service-restful-api).
4. 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.

{% hint style="info" %}
**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.
{% endhint %}

## Set up service accounts when you use SSO-only logins <a href="#set-up-service-accounts-when-you-use-sso-only-logins" id="set-up-service-accounts-when-you-use-sso-only-logins"></a>

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 <a href="#build-custom-api-endpoints-with-http-triggered-flows" id="build-custom-api-endpoints-with-http-triggered-flows"></a>

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](https://support.attackforge.com/app/modules/flows#http-trigger-authentication).

## Look after your service accounts <a href="#look-after-your-service-accounts" id="look-after-your-service-accounts"></a>

* **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 <a href="#tips" id="tips"></a>

* **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 <a href="#faq" id="faq"></a>

**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 <a href="#related-pages" id="related-pages"></a>

* [Self-Service REST APIs](https://docs.attackforge.com/rest-api/pages/getting-started)
* [Users](https://support.attackforge.com/app/modules/users)
* [Groups](https://support.attackforge.com/app/modules/groups)
* [Flows](https://support.attackforge.com/app/modules/flows)
* [Access Control Matrix](https://support.attackforge.com/app/access-control-matrix)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://support.attackforge.com/app/automations-and-integrations/working-with-service-accounts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
