---
title: "API keys, scoped and logged"
description: "Workspace API keys you limit to the scopes and senders a job needs, rotate without breaking anything, and audit call by call."
url: "https://openemail.uk/features/api-keys"
---

[Developers](https://openemail.uk/features.md#developers)

# API keys A key for each job, and nothing more.

Give each service its own key, holding only the scopes and senders it needs. Every call it makes is on the record.

[Open mail](https://openemail.uk/mail/inbox) [Get Started](https://openemail.uk/signup.md)[All features](https://openemail.uk/features.md)

In short

## What is an API key?

A secret your code sends with each request. It says which workspace the call is for and what it is allowed to do.

32

scopes to choose from

25

whole domains in one send scope

3,650

days, the longest expiry

How it works

## A role as a ceiling

Attach a role and the key can never do more than it allows. GET /ping shows what the key names and what the role left it.

## Limit who it sends as

Up to 25 whole domains and 50 single addresses. A sender outside them gets a 403.

## Every call on the record

Method, path, status, error and duration for each request, with the busiest routes and how often they fail.

## Check what a key can do

GET /ping needs no scope and answers with the key's reach.

grantedScopes is what is left once the role is applied.

```
{  "ok": true,  "keyId": "4c1b257a66287fd113bd89d0",  "mode": "live",  "scopes": ["emails:send", "templates:write", "members:write"],  "roleId": "role_2b81de079c1f0a4b7e05d386",  "grantedScopes": ["emails:send", "templates:write"],  "workspaceId": "10417196-e324-4283-af98-66ec62167c47"}
```

What you get

## In the product today

Rotate in place

A new secret, with the same id, scopes and history.

Revoked, not deleted

A later call is told revoked\_api\_key.

Expiry built in

Set a key to lapse, up to ten years out.

Good practice

## Getting the most out of it

1. 01
   
   One key per service
   
   A leak then costs one integration, not all of them.
2. 02
   
   Grant the least
   
   Start from emails:send and add scopes when a call needs them.
3. 03
   
   Watch the failures
   
   Filter the request log to failed calls after a deploy.

Where it stands

## Good to know

Questions

## Asked often

Keep going

## Works well with

Email API

Send one message or a hundred per call, now or later, and retry without sending twice.

REST API

A documented HTTP API with issuable, scopable, revocable keys.

Roles & permissions levels

A role says what somebody may do; an address grant says what they may do it to.

Start

## Your domain, your mail.

Point a domain at OpenEmail and read it in a mailbox built around it. The free plan covers one domain.

[Open mail](https://openemail.uk/mail/inbox) [Get Started](https://openemail.uk/signup.md)[Read the reference](https://openemail.uk/docs/knowledge/developers/api-keys.md)