Authenticating API Requests

Using access tokens

Each request against the EmailEngine API needs to be authenticated with an access token. There is no way to turn this requirement off as some parts of EmailEngine (e.g., the hosted authentication feature) assume that EmailEngine is publicly accessible.

Generating an access token

You can generate access tokens from the "Access tokens" page in the EmailEngine's administration dashboard.

Each access token can have a specific scope assigned. For example, if you monitor EmailEngine with Prometheus, then use the Metrics scope. There is no need to allow full API access if you only need monitoring data.

An access token is shown only once. If you have closed the dialog that displays it, there is no way to see the value again as EmailEngine does not store actual tokens but only hashes.

You can also prepare tokens and set these programmatically, see Prepared Access Token.

Making API requests

EmailEngine uses Bearer authorization. When making API requests, you have to set an Authorization header with the Bearer scheme.

Authorization: Bearer <token>

Where

  • <token> is the access token you generated on the access tokens page

For example, if you have generated a token with the value of "abcdef", then you can make requests with curl using the following arguments:

$ curl http://127.0.0.1:3000/v1/stats -H "Authorization: Bearer abcdef"

{
  "version": "2.8.0",
  "license": "AGPL-3.0-or-later OR LICENSE_EMAILENGINE",
  "accounts": 2,
  "node": "16.13.1",
...

Alternatively, if you are unable to set HTTP headers, you can pass the token as a query argument access_token. 

$ curl http://127.0.0.1:3000/v1/stats?access_token=abcdef"

Using Prometheus

EmailEngine provides a scraping endpoint for Prometheus at "/metrics", e.g., http://127.0.0.1:3000/metrics. These requests need to be authorized as well. Use the Metrics scope when generating an access token for Prometheus.

Use the following configuration for the scraping job in the scrape_configs section to enable authorization:

authorization:
  type: Bearer
  credentials: <token>

Full example

This is an example for a Prometheus scraping job definition for EmailEngine.

  - job_name: 'emailengine'
    scrape_interval: 10s
    metrics_path: '/metrics'
    scheme: 'http'
    authorization:
      type: Bearer
      credentials: e209fc049632c....46dabbb7cd28
    static_configs:
    - targets: ['127.0.0.1:3000']

If you only want to check if the metrics endpoint is working, you can use the same curl command as with regular API requests.

$ curl http://127.0.0.1:3000/metrics -H "Authorization: Bearer abcdef"

# HELP thread_starts Number of started threads
# TYPE thread_starts counter
thread_starts 7

# HELP thread_stops Number of stopped threads
# TYPE thread_stops counter
thread_stops 0
...