How to create an API key

Requirements

You must have the Developer or Admin role to create, edit or delete API keys. If your organization uses custom roles, your role needs the Manage API Keys permission.

This article shows you how to create an API key, choose what it’s allowed to do, and change or delete it later.

An API key lets a script, integration or tool, such as the EDS SDK, sign in to the EmailShepherd API. Each key has a set of scopes, which control exactly what it can access.

Create an API key

1. Navigate to Organization settings > API Keys.

2. Click Create API key.

   

3. In Name, enter a name that says what the key is for, such as EDS SDK or Transactional emails, so you can recognize it later.

4. Under Permission scopes, tick the scopes the key needs. See Choose scopes.

5. Click Create API key.

6. Copy the token and store it somewhere safe, such as a password manager or your secrets store.

7. Click Done.

   

Caution

The token is only shown once. If you lose it, delete the key and create a new one.

Choose scopes

Scopes are grouped by what they give access to, such as Emails, Projects and Image library. Most groups have Read, Write and Delete scopes, and some have extra ones, such as Publish for emails.

To find a scope quickly, type in Search scopes.

Give each key only the scopes it needs. A key can do exactly what its scopes allow and nothing more, so a key that only reads emails can’t change or delete them.

Each endpoint in the API reference lists the scope it needs.

Change a key’s name or scopes

1. Navigate to Organization settings > API Keys.
2. Click the edit icon next to the key.
3. Change the Name or Permission scopes.
4. Click Update API key.

The token stays the same, so anything already using the key keeps working with its new scopes.

Delete a key

1. Navigate to Organization settings > API Keys.
2. Click the delete icon next to the key.
3. Confirm that you want to delete it.

Caution

Deleting a key can’t be undone. Anything using the key stops working straight away.

Next steps

To make your first request with your new key, see How to authenticate with the API.