API Keys

• Table of Contents
• Introduction
• Authenticating with an API key
• Creating an API key
• Viewing API keys
• Deleting an API key
• Permissions

Introduction

An API key lets a program authenticate to GreenArrow without the password of an Engine User. Use an API key for integrations, so that you can revoke the integration’s access without changing a user’s password.

An API key authenticates to:

• The GreenArrow Engine Configuration API, with full API access.
• The HTTP Submission API, for message injection.
• The Mailgun-compatible Domains API (GreenArrow CloudMTA only), with HTTP basic authentication.
• The Mailgun-compatible Messages API (GreenArrow CloudMTA only), for message injection, with HTTP basic authentication.

An API key cannot sign in to GreenArrow’s web interface.

Authenticating with an API key

Use the username api and the API key as the password.

For the GreenArrow Engine Configuration API, send them with HTTP basic authentication:

curl -u "api:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
  http://127.0.0.1/ga/api/v3/eng/ip_addresses

For the HTTP Submission API, send them in the username and password fields of the request document:

{
  "username": "api",
  "password": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "message": {
    ...
  }
}

The username api is reserved for API keys. GreenArrow does not check it against Engine Users.

Creating an API key

1. Navigate to the “API Keys” section of the “Configure” menu.
2. Click “Add API Key”.
3. Enter a description that tells you where the key is used, then click “Save”.
4. Copy the key that is shown.

GreenArrow shows the key only once, when it is created. GreenArrow stores a hash of the key, not the key itself, so it cannot show the key again. If you lose a key, delete it and create a new one.

A key is 64 hexadecimal characters.

Viewing API keys

The “API Keys” page lists each key’s description, the time it was created, and the first 8 characters of the key, for example e3b0c442.... Use the first 8 characters to identify which key an integration uses.

Deleting an API key

1. Navigate to the “API Keys” section of the “Configure” menu.
2. Click “Delete” next to the key, and confirm.

The Engine Configuration API and Mailgun-compatible Domains API refuse a deleted key immediately. In a cluster, MTA instances check HTTP Submission API and Mailgun-compatible Messages API keys against their copy of the configuration, so they refuse a deleted key after their next configuration sync.

Permissions

Engine Users whose UI permission allows editing can create and delete API keys. Engine Users with read-only UI permission can view the list of keys.

Failed API key attempts do not lock out a user. A key is 256 random bits, so it cannot be guessed.