Heimdall API Documentation

Heimdall CRUD Capabilities

Heimdall CRUD Capabilities

Heimdall provides the following capabilities via CRUD operations:

• Upload scans from a pipeline of command line
• Programmatic API Key Generation
• Associate API keys to users and groups

How to Generate an API Key for a Group

How to Generate an API Key for a Group

Heimdall provides the ability for groups to have API key to be used with the API to communicate with the application via the CLI.

To add a API key to a group, select "My Groups" from the user menu:

Select the "Edit" pencil icon to open the "Update Groups" dialog window:

On the "Update Groups" dialog window, click on "Manage API KEYS" link to open the "Group API Keys" dialog window:

The "Group API Keys" dialog window allows the user to do the following:

• Add an API Key to the group
• Regenerate an new API Key (if the old one is lost or compromised)
• Delete an API Key

Programmatic API Key Generation

Programmatic API Key Generation

In order to generate an API key for a user programmatically, you must create a login session for either the admin account or the account of the user for which you wish to create an API key.

Login via API

curl '<your-heimdall-instance>:<PORT>/authn/login' \
  -H 'Content-Type: application/json' \
  --data-raw '{"email":"<email>","password":"<password>"}'

NOTES:

• If you are running Heimdall via a local Docker deployment, you may not need a PORT, given that it is likely running on standard 443 or 80.
• Add -k to ignore SSL certificate validation. This is unsafe. Do not use in production.
• If your login is handled through a third party authentication service, you must complete the third party login flow programmatically or insert a user record into the database containing the email address of the user for which you wish to create the API key

The server will return a live JWT token in response

{
	"userID": "1",
	"accessToken": "eyJhbGc...rqA3Zo"
}

The access token can then be used to issue an API key for a user

curl 'http://localhost:8080/apikeys' \
  -H 'Authorization: Bearer eyJhbGc...rqA3Zo' \
  -H 'Content-Type: application/json' \
  --data-raw '{"userId":"<User ID>","currentPassword":"<Password>"}' \
  --compressed

or

curl 'http://localhost:8080/apikeys' \
  -H 'Authorization: Bearer eyJhbGc...rqA3Zo' \
  -H 'Content-Type: application/json' \
  --data-raw '{"userEmail":"<User Email>","currentPassword":"<Password>"}' \
  --compressed

The server will respond with the newly generated API key

{
	"id": "3", // This is the ID of the API key
	"name": null,
	"apiKey": "eyJhbGciOi...kPrGBVDOU"
}