# GETTING STARTED
## Overview
This page will help you to get started with using the Self-Service Events API.
You can use the Self-Service Events API to:
* Receive real-time notifications on vulnerabilities for your projects, and export them into your vulnerability management and/or ticketing systems.
* Receive real-time notifications on vulnerabilities for your projects, and update your existing dashboard applications with live notifications.
* Receive real-time notifications on new projects and changes to existing projects.
* Receive real-time notifications when testing starts & stops daily on your projects.
* Receive real-time notifications when vulnerabilities are ready for retesting, closed or re-opened.
* Receive real-time notifications on audit logs and user activities.
## Prerequisites
In order to receive events, you must first get access to Events by your administrators. Access can be provided from `Users > (select user) > Access > Events > Add Events`
Authentication to the Self-Service Events API is controlled using the [User API Key](https://support.attackforge.com/attackforge-enterprise/getting-started/manage-user#user-key).
In order to access the Self-Service Events API, you must meet the following conditions:
* You must have a valid [User API Key](https://support.attackforge.com/attackforge-enterprise/getting-started/manage-user#user-key);
* You must be provided with access to Events by the Administrators;
* You must have Network access to your AttackForge Enterprise tenant
All requests to the Events API must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate all requests.
## Accessing the Events API
Access to the Events API, including scope of data available, is *restricted to the users' data within the application*.
Every user in the application *does not* have access to any of the Events, by default. This includes Administrators.
Access to the Events API must be provided explicitly by an Administrator, and is controlled on an individual event basis.
A user can see their access to the Events API by viewing the SSAPI module in the application.
The following padlocks indicate that the Event is not available:
## Setting up your client
In order to receive events, you must first set up your client and subscribe the client to events which you have access to.
To help make the setup process simple & fast, we have included ready-to-use clients which take only minutes to set up and start using.
Each client is production-ready, includes step-by-step instructions and is provided in multiple programming languages - to ensure compatibility & ease of use with your technologies and teams.
* NodeJS
* Python
* .NET
* Java
* Go
### NodeJS
#### Prerequisites
In order to use the NodeJS client, you must have:
* NodeJS v10+ installed
* NPM installed
* Network access to your AttackForge Enterprise tenant
#### Step 1: Download the NodeJS client
You can download or clone the NodeJS client from AttackForge public Git repository:
**Website**
* [Web](https://github.com/AttackForge/afe-ssapi-events-nodejs-client.git)
**Clone**
```
git clone https://github.com/AttackForge/afe-ssapi-events-nodejs-client.git
```
**Direct download**
* [Zip](https://github.com/AttackForge/afe-ssapi-events-nodejs-client/archive/refs/heads/main.zip)
#### Step 2: Install dependancies
Using a terminal, navigate to the directory when you downloaded the client in Step 1.
```
$ cd ~/Documents/afe-ssapi-events-nodejs-client
```
Using NPM, install dependancies from package.json.
```
$ npm install
```
#### Step 3: Run client
Run following command, substituting variables below with your configuration details:
```
$ HOSTNAME="YOUR-AFE-HOSTNAME" EVENTS="YOUR-EVENTS" X_SSAPI_KEY="YOUR-API-KEY" node .
```
An example is included below for reference:
```
$ HOSTNAME="demo.attackforge.com" EVENTS="vulnerability-created,vulnerability-updated" X_SSAPI_KEY="q9ef672kqZIQymCZRuiKMeWbeaXEzBzqRCfGcpWEpoBNU2Bk4UmtktsZVDDgRzlC0BOHH9x0y4EzbBGeSKO9PRskEmHATXHs2sVe7tS98U0DuDFjH0RdPFWUpgZDWgIESy9yNDesm6Xi8C9HsikddyBKsATXat2604dPrr4Ca86J8Y5IkEnqUwYzw3MoSbzHeXZ0DKHqKz6Icv9dtrsnAFzpXg1P423uRllq4LqFjP4J8hAtrWZ9296h3uh9B5Vp" node .
```
If your client is successfully subscribed to the events, you should see similar output in your terminal:
```
Subscribed to the following events: [ 'vulnerability-created', 'vulnerability-updated' ]
```
Your client is now working and you will see new events output to the terminal as they are pushed from AttackForge.
You can now work on your integration code to start actioning these events. Open **index.js** with a text editor - the file is located in your client directory. Your code will replace the following section within this file:
```
/* ENTER YOUR INTEGRATION CODE HERE */
/* method contains the event type e.g. vulnerability-created */
/* params contains the event body e.g. JSON object with timestamp & vulnerability details */
```
### Python
#### Prerequisites
In order to use the Python client, you must have:
* Python3 installed
* PIP installed
* Network access to your AttackForge Enterprise tenant
#### Step 1: Download the Python client
You can download or clone the Python client from our public Git repository:
**Website**
```
https://github.com/AttackForge/afe-ssapi-events-python-client.git
```
**Clone**
```
git clone https://github.com/AttackForge/afe-ssapi-events-python-client.git
```
**Direct Download**
```
https://github.com/AttackForge/afe-ssapi-events-python-client/archive/refs/heads/main.zip
```
#### Step 2: Install dependancies
Using a terminal, navigate to the directory when you downloaded the client in Step 1.
```
$ cd ~/Documents/afe-ssapi-events-python-client
```
Using PIP, install dependancies from main.py.
```
$ pip3 install websockets
```
#### Step 3: Run client
Run following command, substituting variables below with your configuration details:
```
$ HOSTNAME="YOUR-AFE-HOSTNAME" EVENTS="YOUR-EVENTS" X_SSAPI_KEY="YOUR-API-KEY" python3 main.py
```
An example is included below for reference:
```
$ HOSTNAME="demo.attackforge.com" EVENTS="vulnerability-created,vulnerability-updated" X_SSAPI_KEY="q9ef672kqZIQymCZRuiKMeWbeaXEzBzqRCfGcpWEpoBNU2Bk4UmtktsZVDDgRzlC0BOHH9x0y4EzbBGeSKO9PRskEmHATXHs2sVe7tS98U0DuDFjH0RdPFWUpgZDWgIESy9yNDesm6Xi8C9HsikddyBKsATXat2604dPrr4Ca86J8Y5IkEnqUwYzw3MoSbzHeXZ0DKHqKz6Icv9dtrsnAFzpXg1P423uRllq4LqFjP4J8hAtrWZ9296h3uh9B5Vp" python3 main.py
```
If your client is successfully subscribed to the events, you should see similar output in your terminal:
```
Subscribed to the following events: [ 'vulnerability-created', 'vulnerability-updated' ]
```
Your client is now working and you will see new events output to the terminal as they are pushed from AttackForge.
You can now work on your integration code to start actioning these events. Open **main.py** with a text editor - the file is located in your client directory. Your code will replace the following section within this file:
```
# ENTER YOUR INTEGRATION CODE HERE
# method contains the event type e.g. vulnerability-created
# params contains the event body e.g. JSON object with timestamp & vulnerability details
```
### .NET
#### Prerequisites
In order to use the .NET client, you must have:
* .NET 5.0 SDK installed
* Network access to your AttackForge Enterprise tenant
#### Step 1: Download the .NET 5.0 client
You can download or clone the .NET 5.0 client from our public Git repository:
**Website**
```
https://github.com/AttackForge/afe-ssapi-events-dotnet-client.git
```
**Clone**
```
git clone https://github.com/AttackForge/afe-ssapi-events-dotnet-client.git
```
**Direct Download**
```
https://github.com/AttackForge/afe-ssapi-events-dotnet-client/archive/refs/heads/main.zip
```
#### Step 2: Run client
Run following command, substituting variables below with your configuration details:
```
$ HOSTNAME="YOUR-AFE-HOSTNAME" EVENTS="YOUR-EVENTS" X_SSAPI_KEY="YOUR-API-KEY" dotnet run
```
An example is included below for reference:
```
$ HOSTNAME="demo.attackforge.com" EVENTS="vulnerability-created,vulnerability-updated" X_SSAPI_KEY="q9ef672kqZIQymCZRuiKMeWbeaXEzBzqRCfGcpWEpoBNU2Bk4UmtktsZVDDgRzlC0BOHH9x0y4EzbBGeSKO9PRskEmHATXHs2sVe7tS98U0DuDFjH0RdPFWUpgZDWgIESy9yNDesm6Xi8C9HsikddyBKsATXat2604dPrr4Ca86J8Y5IkEnqUwYzw3MoSbzHeXZ0DKHqKz6Icv9dtrsnAFzpXg1P423uRllq4LqFjP4J8hAtrWZ9296h3uh9B5Vp" dotnet run
```
If your client is successfully subscribed to the events, you should see similar output in your terminal:
```
Subscribed to the following events: [ 'vulnerability-created', 'vulnerability-updated' ]
```
Your client is now working and you will see new events output to the terminal as they are pushed from AttackForge.
You can now work on your integration code to start actioning these events. Open **Program.cs** with a text editor from your client directory. Your code will replace the following section within this file:
```
/* ENTER YOUR INTEGRATION CODE HERE */
/* method contains the event type e.g. vulnerability-created */
/* params contains the event body e.g. JSON object with timestamp & vulnerability details */
```
### Java
#### Prerequisites
In order to use the Java client, you must have:
* OpenJDK 11 installed
* Maven installed
* Network access to your AttackForge Enterprise tenant
#### Step 1: Download the Java client
You can download or clone the Java client from our public Git repository:
**Website**
```
https://github.com/AttackForge/afe-ssapi-events-java-client.git
```
**Clone**
```
git clone https://github.com/AttackForge/afe-ssapi-events-java-client.git
```
**Direct Download**
```
https://github.com/AttackForge/afe-ssapi-events-java-client/archive/refs/heads/main.zip
```
#### Step 2: Install dependancies
Using a terminal, navigate to the directory when you downloaded the client in Step 1.
```
$ cd ~/Documents/afe-ssapi-events-java-client
```
Using Maven, install dependancies and build the Java client as a JAR.
```
$ mvn clean compile assembly:single
```
#### Step 3: Run client
Run following command, substituting variables below with your configuration details:
```
$ HOSTNAME="YOUR-AFE-HOSTNAME" EVENTS="YOUR-EVENTS" X_SSAPI_KEY="YOUR-API-KEY" java -jar target/afe-ssapi-events-java-client-1.0-SNAPSHOT-jar-with-dependencies.jar
```
An example is included below for reference:
```
$ HOSTNAME="demo.attackforge.com" EVENTS="vulnerability-created,vulnerability-updated" X_SSAPI_KEY="q9ef672kqZIQymCZRuiKMeWbeaXEzBzqRCfGcpWEpoBNU2Bk4UmtktsZVDDgRzlC0BOHH9x0y4EzbBGeSKO9PRskEmHATXHs2sVe7tS98U0DuDFjH0RdPFWUpgZDWgIESy9yNDesm6Xi8C9HsikddyBKsATXat2604dPrr4Ca86J8Y5IkEnqUwYzw3MoSbzHeXZ0DKHqKz6Icv9dtrsnAFzpXg1P423uRllq4LqFjP4J8hAtrWZ9296h3uh9B5Vp" java -jar target/afe-ssapi-events-java-client-1.0-SNAPSHOT-jar-with-dependencies.jar
```
If your client is successfully subscribed to the events, you should see similar output in your terminal:
```
Subscribed to the following events: [ 'vulnerability-created', 'vulnerability-updated' ]
```
Your client is now working and you will see new events output to the terminal as they are pushed from AttackForge.
You can now work on your integration code to start actioning these events. Open **./src/main/java/com/attackforge/App.java** with a text editor from your client directory. Your code will replace the following section within this file:
```
/* ENTER YOUR INTEGRATION CODE HERE */
/* method contains the event type e.g. vulnerability-created */
/* params contains the event body e.g. JSON object with timestamp & vulnerability details */
```
### Go
#### Prerequisites
In order to use the Go client, you must have:
* Go installed
* Network access to your AttackForge Enterprise tenant
#### Step 1: Download the Go client
You can download or clone the Go client from our public Git repository:
**Website**
```
https://github.com/AttackForge/afe-ssapi-events-go-client.git
```
**Clone**
```
git clone https://github.com/AttackForge/afe-ssapi-events-go-client.git
```
**Direct Download**
```
https://github.com/AttackForge/afe-ssapi-events-go-client/archive/refs/heads/main.zip
```
#### Step 2: Build client
Using a terminal, navigate to the directory when you downloaded the client in Step 1.
```
$ cd ~/Documents/afe-ssapi-events-go-client
```
Using Go, install dependancies and build the client.
```
$ go build
```
#### Step 3: Run client
Run following command, substituting variables below with your configuration details:
```
$ HOSTNAME="YOUR-AFE-HOSTNAME" EVENTS="YOUR-EVENTS" X_SSAPI_KEY="YOUR-API-KEY" ./afe-ssapi-events-go-client
```
An example is included below for reference:
```
$ HOSTNAME="demo.attackforge.com" EVENTS="vulnerability-created,vulnerability-updated" X_SSAPI_KEY="q9ef672kqZIQymCZRuiKMeWbeaXEzBzqRCfGcpWEpoBNU2Bk4UmtktsZVDDgRzlC0BOHH9x0y4EzbBGeSKO9PRskEmHATXHs2sVe7tS98U0DuDFjH0RdPFWUpgZDWgIESy9yNDesm6Xi8C9HsikddyBKsATXat2604dPrr4Ca86J8Y5IkEnqUwYzw3MoSbzHeXZ0DKHqKz6Icv9dtrsnAFzpXg1P423uRllq4LqFjP4J8hAtrWZ9296h3uh9B5Vp" ./afe-ssapi-events-go-client
```
If your client is successfully subscribed to the events, you should see similar output in your terminal:
```
Subscribed to the following events: [ 'vulnerability-created', 'vulnerability-updated' ]
```
Your client is now working and you will see new events output to the terminal as they are pushed from AttackForge.
You can now work on your integration code to start actioning these events. Open **main.go** with a text editor from your client directory. Your code will replace the following section within this file:
```
/* ENTER YOUR INTEGRATION CODE HERE */
/* method contains the event type e.g. vulnerability-created */
/* params contains the event body e.g. JSON object with timestamp & vulnerability details */
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://support.attackforge.com/attackforge-enterprise/modules/self-service-events-api/getting-started.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.