> 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/self-service-restful-api.md).

# Self-Service RESTful API

## Overview

The Self-Service RESTful API lets you read and change AttackForge data from your own scripts and systems: create projects, import vulnerabilities, download reports, upload files and more. Each user calls the API with their own API key, and can use only the API methods an administrator has given them.

{% hint style="info" %}
**Tip:** For every API method and endpoint, see the [API documentation](https://docs.attackforge.com/rest-api/pages/getting-started).
{% endhint %}

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FvSEyftCJijo5nOxaK4oQ%2Fself-service-restful-api-at-a-glance.svg?alt=media&amp;token=ee7e3188-87b7-4e1a-83ab-f21b3b91de43" alt=""><figcaption></figcaption></figure>

## Why it matters

| Benefit                         | What it means                                                                         |
| ------------------------------- | ------------------------------------------------------------------------------------- |
| **Automate repetitive work**    | Create projects, import findings and update records without clicking through the app  |
| **Connect your tools**          | Link AttackForge to ticketing, scanning, CI/CD, SIEM and reporting systems            |
| **Least privilege**             | Every method is off by default. Each user, or group, gets only the methods they need. |
| **Each user has their own key** | Requests are tied to a person, so access and activity are easy to trace               |
| **Act on a user's behalf**      | Administrators can run requests as another user, within that user's permissions       |

## Who uses it

| Role                                     | Typical use                                                    |
| ---------------------------------------- | -------------------------------------------------------------- |
| **Administrators**                       | Grant API methods to users and groups, and set up Run-As users |
| **Developers and integration engineers** | Build integrations with scanners, ticketing and CI/CD          |
| **Testers and consultants**              | Script imports, report downloads and bulk updates              |
| **Automation builders**                  | Call the API from scripts, agents and other platforms          |

## Choose the right integration

| Use                                                                                              | When you want to                                                           |
| ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| [**Self-Service RESTful API**](https://docs.attackforge.com/rest-api/pages/getting-started)      | Read or change data from your own code, on demand                          |
| [**Flows**](https://support.attackforge.com/app/automations-and-integrations/flows)              | Run automation inside AttackForge when something happens, or on a schedule |
| [**Actions**](https://support.attackforge.com/app/automations-and-integrations/actions)          | Let users start a Flow from a button in the app                            |
| [**AI MCP**](https://support.attackforge.com/app/automations-and-integrations/ai-mcp-and-skills) | Let an AI assistant or agent work with your data                           |
| [**Events API**](https://docs.attackforge.com/events-api)                                        | React to AttackForge events in your own systems.                           |

## See which API methods you can use

Go to **Integration Docs** in the main menu to see the API methods.

A padlock next to a method means you don't have access to it.

{% hint style="info" %}
**Important:** Every API method is off by default for every user, including administrators.
{% endhint %}

You can get access in two ways:

* An administrator gives you access to the method directly.
* An administrator gives a group access to the method, and you're a member of that group.

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FXwWPKyzPE5Nt9qfSM4eP%2Fimage.png?alt=media&amp;token=a1c5fb2b-0475-4976-a122-1bbd73b35725" alt=""><figcaption></figcaption></figure>

## Give users access to API methods

### Give one user access

1. Go to **Users**, select the user, and click **Access**.
2. Expand **Self-Service RESTful API**, and click **Add Methods**.
3. Select the methods, and click **Add**.

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FLPseVOpNlbT1XFja7maX%2Fimage.png?alt=media&amp;token=00987f11-ea71-4886-8393-697f0fe31378" alt=""><figcaption></figcaption></figure>

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FmtViMvD9mYMANlmuZZmj%2Fimage.png?alt=media&amp;token=65943909-281e-4f1d-8896-20b900fa1d9d" alt=""><figcaption></figcaption></figure>

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2F4Zw1aclRoJKbFlO31kwI%2Fimage.png?alt=media&amp;token=cd7a83d6-e18b-4d1e-9e99-61b1f04ba431" alt=""><figcaption></figcaption></figure>

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2F4QWpfQPVhwMggB1HvuRY%2Fimage.png?alt=media&amp;token=23a7c3ab-a72a-499d-8fda-c7ae9ef3288e" alt=""><figcaption></figcaption></figure>

### Give a group access

1. Go to **Groups**, select the group, and click **Other Access**.
2. Expand **Self-Service RESTful API**, and click **Add Methods**.
3. Select the methods, and click **Add**.

{% hint style="info" %}
**Note:** Every member of the group can use the methods you give the group.
{% endhint %}

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2Fu3VGAcBu8iDX2BZZ954B%2Fimage.png?alt=media&amp;token=b2184044-aad8-4466-8e86-5992142bb066" alt=""><figcaption></figcaption></figure>

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FlDftQkQusd7nvDYq0ada%2Fimage.png?alt=media&amp;token=a906db40-5e23-42df-9837-140285d7c585" alt=""><figcaption></figcaption></figure>

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FGwfRqwLd9mXkYSMOgnqT%2Fimage.png?alt=media&amp;token=718145b7-a7ec-4941-9b93-05aa6e1bb256" alt=""><figcaption></figcaption></figure>

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FeGzqykbyaU8DwvBhjIMv%2Fimage.png?alt=media&amp;token=e5b9bb80-24a5-4058-a6f5-fa634fa0207f" alt=""><figcaption></figcaption></figure>

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2F2ppYUnOy2OL7PN2yacoX%2Fimage.png?alt=media&amp;token=2fe8b10e-3044-4e69-b074-daf9875c4fc0" alt=""><figcaption></figcaption></figure>

## Create your API key

1. Log in to AttackForge, and go to **Profile**.
2. Click **Secrets**.
3. Under **API Key**, click **View Key**, **Copy Key** or **Rotate Key**.

{% hint style="info" %}
**Warning:** Users can only create, view and rotate their own key. Administrators can't do this for other users.
{% endhint %}

Rotating your key stops the old key working straight away, so update any script that uses it.

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FXTNBHZEweAXKPSFEEkVF%2Fimage.png?alt=media&amp;token=d367866c-d968-4140-91cc-d5b423e3736f" alt=""><figcaption></figcaption></figure>

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FQk8lyaK9WPXR1ty4Ngq5%2Fimage.png?alt=media&amp;token=3f671daa-56ee-4223-9932-73a31e97201a" alt=""><figcaption></figcaption></figure>

### Make your first request

Send your API key in the `X-SSAPI-KEY` header with each request.

This example lists the projects you can see. Replace `{{ATTACKFORGE-HOSTNAME}}` with your hostname and `{{API-KEY}}` with your key:

```bash
curl -X GET "https://{{ATTACKFORGE-HOSTNAME}}/api/ss/projects" \
  -H "Host: {{ATTACKFORGE-HOSTNAME}}" \
  -H "X-SSAPI-KEY: {{API-KEY}}" \
  -H "Content-Type: application/json" \
  -H "Connection: close"
```

The request works only if you have access to that method. For each method's URL, parameters and response, see the [API documentation](https://docs.attackforge.com/rest-api/pages/getting-started).

## Run requests as another user

Administrators can make API requests on behalf of another user. Use this to:

* run automation as the right person
* troubleshoot a user's problem
* check what a user can see and do
* keep permissions tight, while managing everything from one admin API key

<figure><img src="https://372186556-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M8s1QY2Q6YTHB4a6DMu%2Fuploads%2FjkquN2Vtw7XDKkKJQ5Sj%2Fimage.png?alt=media&amp;token=25db3e7c-ff73-47c7-bab1-feba478b0bc1" alt=""><figcaption></figcaption></figure>

### Set it up

1. Go to **Users > Access > Self Service RESTful API > Run-As Users**, and add the users you need.
2. Copy each user's **System ID**. Hover over the user in the table to copy it.
3. Send the `x-run-as-user-id` header, set to that System ID, with your API key. The request runs as that user.

{% hint style="info" %}
Run-As Users are added on the administrator's own access, not on each user's.
{% endhint %}

Example:

```bash
curl -X GET "https://{{ATTACKFORGE-HOSTNAME}}/api/ss/projects" \
  -H "X-SSAPI-KEY: {{ADMIN-API-KEY}}" \
  -H "x-run-as-user-id: {{USER-SYSTEM-ID}}" \
  -H "Content-Type: application/json"
```

### How it stays secure

* The request can use only the API methods the user already has. Run-As never adds permissions.
* Only non-admin users can be added as Run-As users.

## Tips

* **Grant methods to groups.** Group access is easier to manage and review than user-by-user access.
* **Give the fewest methods you can.** Start with read methods, and add write methods only when they're needed.
* **Use a dedicated user for integrations.** An integration with its own user and key is easy to trace and to switch off.
* **Keep your key secret.** Store it in a secrets manager or environment variable, never in code or a shared file.
* **Rotate keys regularly,** and straight away if one may have been exposed.
* **Use Run-As to test permissions.** Check what a user can see and do without asking for their key.
* **Store reports back on the project.** Upload a generated report with the API so it's kept with the project. See [Report automation](https://support.attackforge.com/app/automations-and-integrations/report-automation).
* **Consider AI MCP for ad hoc questions.** If people want to ask questions of their data rather than build an integration, [AI MCP](https://support.attackforge.com/app/automations-and-integrations/ai-mcp-and-skills) may suit them better.

## FAQ

**Why do I see a padlock next to a method?** You don't have access to it. Ask an administrator to give you, or one of your groups, access.

**I'm an administrator. Why can't I use the API?** Every method is off by default, including for administrators. Give yourself access to the methods you need.

**Can an administrator create or see my API key?** No. Only you can create, view and rotate your own key.

**What happens to my scripts when I rotate my key?** The old key stops working, so update your scripts with the new key.

**Can Run-As give a user more access?** No. A Run-As request can use only the methods that user already has.

**Can I run requests as another administrator?** No. Only non-admin users can be Run-As users.

**Where can I find a user's System ID?** In the Run-As Users table, hover over the user to copy it.

**Where's the full list of API methods?** In **Integration Docs** in the app, and in the [API documentation](https://docs.attackforge.com/rest-api/pages/getting-started).

## Related pages

* [API documentation](https://docs.attackforge.com/rest-api/pages/getting-started): every API method, with parameters and examples.
* [AI MCP and Skills](https://support.attackforge.com/app/automations-and-integrations/ai-mcp-and-skills): let AI assistants work with your data.
* [AI agentic workflows](https://support.attackforge.com/app/automations-and-integrations/ai-agentic-workflows): run AI agents with AttackForge.
* [Flows](https://support.attackforge.com/app/automations-and-integrations/flows): automate work inside AttackForge.
* [Actions](https://support.attackforge.com/app/automations-and-integrations/actions): start Flows from the app.
* [Report automation](https://support.attackforge.com/app/automations-and-integrations/report-automation): generate reports and upload them with the API.
* [Administration](https://support.attackforge.com/app/modules/administration): manage users and groups.


---

# 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/self-service-restful-api.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.
