API Reference

Update API key

PATCH /api-keys/:id — rename a key or change its permission and domain restriction.

PATCH/api-keys/:id

Updates an API key in place — no need to mint a new token to change what an existing key may do. Omitted fields stay unchanged. The secret token itself is immutable and never re-shown: to rotate credentials, create a new key and revoke this one. An API-key caller must hold full_access to update keys.

Path parameters

idstringrequired

The API key ID.

Body parameters

namestringoptional

A new label for the key.

permissionfull_access | sending_accessoptional

The new access level. Setting full_access also clears any domain restriction — full-access keys always work across all your domains.

domain_idsstring[] | nulloptional

Replace the key’s domain restriction. Only valid with sending_access. Send null (or an empty array) to allow all domains. Omit the field to leave the current restriction unchanged.

domain_idstringoptional

Legacy single-domain form of domain_ids. Provide one or the other, not both.

const res = await fetch('https://www.mailblastr.com/api/api-keys/dacf4072-4119-4d88-932f-6202748ac7c8', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer mb_xxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "permission": "sending_access",
  "domain_ids": ["b8f9c2aa-4c11-4f24-9d55-1f7a2b3c4d5e"]
}),
});
const data = await res.json();
console.log(data);

Response

{
  "id": "dacf4072-4119-4d88-932f-6202748ac7c8",
  "object": "api_key",
  "name": "Production server",
  "token": "mb_AbC12",
  "permission": "sending_access",
  "domain_id": "b8f9c2aa-4c11-4f24-9d55-1f7a2b3c4d5e",
  "domain_ids": ["b8f9c2aa-4c11-4f24-9d55-1f7a2b3c4d5e"],
  "created_at": "2026-06-23T10:00:00.000Z",
  "last_used_at": "2026-06-25T17:09:51.813Z"
}

Errors: not_found if the key does not exist, is revoked, or is not yours; validation_error if no updatable field is provided, name is empty, permission is invalid, both domain_id and domain_ids are provided, a domain restriction is combined with full_access, or domain_ids references a domain that is not yours; restricted_api_key if the calling key lacks full access.