# Authentication

> API keys for Reggio Digital: how to get one, what each ability allows, limiting a key to a domain, and replacing a key without downtime.

Source: https://reggiodigital.com/developers/authentication

## API keys

Every call carries a key in the `Authorization` header:

```
Authorization: Bearer rgo_your_key_here
```

Keys start with `rgo_`. A key belongs to the business's account, not to the person who created it, so it keeps working when that person leaves the account. Anyone on the account who has been given access to Email can see and manage keys under [Connected apps](https://reggiodigital.com/email/api/keys).

A missing, malformed or revoked key gets a `401` with the error type `unauthorized`.

## Keep the key on your server

A key can send email as the business. Treat it like a password:

- Store it in an environment variable or your platform's secret store.
- Never put it in JavaScript that runs in a browser, in a mobile app bundle, or in a public repository.
- A signup form on a website should post to your own server, and your server calls us.

If a key does leak, replace it straight away (see below). The old one can be stopped the same second.

## Abilities

A key can only do what it was given when it was connected. Give each application the least it needs.

| Ability | Lets the key |
| --- | --- |
| `email:send` | Send, schedule, reschedule, cancel and look up transactional email. |
| `newsletter:read` | Look up lists, custom fields and contacts. Cannot change anything. |
| `newsletter:manage` | Everything `newsletter:read` can, plus add, update and unsubscribe contacts. |

A key without the ability a call needs gets a `403` with the error type `forbidden`. A newsletter key cannot send email, and an email key cannot touch the subscriber list.

The business also needs the product the call belongs to. A valid key on an account with no transactional email plan gets a `402` with `no_plan` from the email endpoints, and the same goes for the newsletter endpoints.

## Limiting a key to sending domains

When you connect an application you can limit its key to one or more of the account's verified sending domains. A limited key:

- can only send from addresses on those domains, and gets a `403` with `send_rejected` for any other from address;
- can only look up, reschedule or cancel messages sent from those domains. Anything else reads as a `404`.

Use this when one account runs several brands, or when a contractor's application should only ever send as one of them.

## One key per application

Connect each application separately rather than sharing one key. Each gets its own name in the dashboard, its own last-used time and its own entries in the [API log](https://reggiodigital.com/email/api/log), and you can replace or switch off one without touching the others.

## Replacing a key

Replacing a key in [Connected apps](https://reggiodigital.com/email/api/keys) creates a new key with the same name, abilities and domain limits, and lets you choose how long the old one keeps working:

- stop straight away, for a key you believe has leaked;
- keep working for an hour, a day or a week, so you can deploy the new key without a gap.

During the overlap both keys are accepted. Scheduled messages sent with the old key move to the new one, so they still go out on time after the old key stops.