Problem types

unauthorized

HTTP 401 — Authentication is required or the API key is invalid.

Returned as application/problem+json with code unauthorized and HTTP status 401.

Authentication failed. The API key is missing, malformed, revoked, or does not match the environment.

Common causes

  • No Authorization header was sent.
  • The header is not in the form Bearer usgmk_….
  • The key was rotated, revoked, or expired.
  • Environment mismatch — a usgmk_test_… key against production, or a usgmk_live_… key against the sandbox.

How to resolve

  • Send Authorization: Bearer usgmk_live_… (or usgmk_test_… against the sandbox).
  • Confirm the key is active in your dashboard; rotate it if needed.
  • Use the key that matches the environment you are calling.

Example

1{
2  "type": "https://docs.usglobalmail.com/api/problems/unauthorized",
3  "title": "Authentication is required or the API key is invalid.",
4  "status": 401,
5  "code": "unauthorized",
6  "request_id": "req_8f3c2a1b9d",
7  "instance": "/v1/mails"
8}
Retrying without changing the request will not help — fix the request first.

See also: authentication.