Create an API key

Mint a new key, and receive its token — once.

http

POST /v1/api-keys

Requires a Full access API key. A key that can create keys can grant itself anything, so a sending key cannot do this.

Body parameters

Parameter	Type	Required	Description
`name`	string	Yes	A label for the key. Max 100 characters.
`permission`	string	No	`full_access` or `sending_access`. Defaults to `full_access`.
`domain_id`	string	No	Restrict a `sending_access` key to one domain — pass the domain id (see Add a domain). Only valid with `sending_access`.

full_access can call every endpoint; sending_access can only send email. Give an embedded or third-party integration a sending_access key, so a leak cannot be used to read your data or reshape your account.

Example

curlNode.js

bash

curl -X POST 'https://api.sendgrail.com/v1/api-keys' \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Production" }'

const res = await fetch('https://api.sendgrail.com/v1/api-keys', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Production' }),
});

const { token } = await res.json();

A domain-scoped sending key:

bash

curl -X POST 'https://api.sendgrail.com/v1/api-keys' \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Marketing sender",
    "permission": "sending_access",
    "domain_id": "d91b1c2e-5f0a-4c3b-9e21-8a7c4d0f1b22"
  }'

Response

json

{
  "object": "api_key",
  "id": "dacf4072-4119-4d88-932f-6202748ac7c8",
  "name": "Production",
  "permission": "full_access",
  "domain": null,
  "created_at": "2026-07-15T10:05:26+00:00",
  "last_used_at": null,
  "token": "sg_c1tpEyD8_NKFusih9vKVQknRAQfmFcWCv"
}

The token is shown once

token is the only time you will ever see the key. We store it as a hash, so there is no endpoint that can give it back to you — retrieving a key returns its metadata, never its token. Copy it somewhere safe when you create it; if you lose it, delete the key and make a new one.

The token is also redacted from your request logs — it comes back as "[redacted]" there. Creating a key over the API does not write that key into a log where another key could later read it.

No update endpoint

A key's permission is fixed once created. To change what a key can do, create a new key with the permission you want and delete the old one — which leaves a clear trail in your logs, where a silent edit would not.

Create an API key ​

Body parameters ​

Example ​

Response ​

The token is shown once ​