Heimdall API Documentation

Heimdall API Capabilities

The Heimdall Application Programming Interface (API) provides the following Representational State Transfer (REST) and Create, Read, Update, and Delete (CRUD) operations:

• Upload scans from a pipeline or Command Line (CMD)
• Programmatic User API Key Generation
• Generate Group API Keys

Important

• To use any available CRUD capabilities provided by Heimdall, the environment variable API_KEY_SECRET must be set (see Environment Variable Configurations).
  
• To create a secret to be used with the API_KEY_SECRET run: openssl rand -hex 33 then assign the value to the variable in the .env configuration file:
  • API_KEY_SECRET=91f82f...082fee

Upload evaluations scans via cURL

Heimdall enables data exchange between a device and the server through a terminal utilizing the client URL (cURL) command line using Users or Groups API Keys.

curl -F "data=@<Path to Evaluation File>" -F "filename=<Filename To Show in Heimdall>" -F "public=true/false" -F "evaluationTags=<tag-name>,<another-tag-name>..." -H "Authorization: Api-Key apikeygoeshere" "http://localhost:3000/evaluations"

NOTE: Flag formats and description

Flag	Description
-F "data=@ ..."	File(s) to be uploaded
-F "filename= ..."	File(s) display name
-H "Authorization: Api-Key ..."	API Key value

To upload multiple files at once (up to 100) use

curl -F "data=@<Path to first evaluation File>" -F "data=@<Path to second evaluation File>" ... -F "public=true/false" -F "evaluationTags=<tag-name>,<another-tag-name>..." -H "Authorization: Api-Key apikeygoeshere" "http://localhost:3000/evaluations"

top

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>"}'

Tip

• 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 returns a live JWT access token in response

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

The access token is used to issue an API key

NOTE: Use the returned accessToken for the -H 'Authorization: Bearer <accessToken>'

Issue an API key utilizing user identification (userID), the one returned by the login API call use:

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

Issue an API key utilizing the user email used for the login API call

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"
}

top

How to Generate API Keys for Groups

Heimdall provides the ability for groups to have API key(s) that can be used to communicate with the application via the CLI.

To add an 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

NOTE: To create a new API Key users must provide their password

Once the Add API Key is clicked a new API Key is generated. Provide a name for the key, copy and store the key value.

top