Sign in to fill these examples with your own keys. Sign in Start free trial

Create an API key

Create a Bearer token in the dashboard and make your first authenticated request.

An API key authenticates REST and MCP requests for one team. SMTP and HTTP inject use cluster credentials instead. See SMTP credentials.

Before you start

You need the Team Administrator role to create or delete a key. See Team roles.

Create the key

  1. In the dashboard, open API keys and click Create API key.
  2. Enter a Name so you can tell keys apart later.
  3. Under Access, choose Send only, Full access, or Support. You can't change it after the key is created.
  4. Save, then copy the Bearer token.

Choose Send only for apps and integrations that only send mail. It is the default for new keys.

Access What it can do
Send only Send email with POST /api/v1/emails or POST /api/v1/teams/{team_id}/clusters/{cluster_id}/sends, including template sends, and call GET /api/v1/users/me. Nothing else.
Full access Everything in the REST API: clusters, domains, credentials, inboxes, webhooks, and sending.
Support Look up a recipient, read analytics, status, events, and suppressions, and remove a suppression. Nothing else. See Create a Support key.

The API keys page also shows your team id. Use it in paths such as /api/v1/teams/{team_id}/clusters.

Test the key

Send the key in the Authorization header. This request returns the user the key belongs to.

whoami.sh
1curl -sS \ 2 -H 'Authorization: Bearer YOUR_API_KEY' \ 3 https://app.postshiba.com/api/v1/users/me
whoami-response.json
1{ 2 "id": "UsErMe", 3 "email": "you@example.com", 4 "first_name": "Ada", 5 "last_name": "Lovelace", 6 "time_zone": "UTC", 7 "locale": null, 8 "created_at": "2026-09-11T12:00:00.000Z", 9 "updated_at": "2026-09-11T12:00:00.000Z" 10}

A missing or revoked key returns 401. Keep keys on your server. Anyone with the token can act on your team with that key's access. A leaked Send only key can send mail, but it cannot read events, recipients, or settings, or change your account.

Keep the key safe

Give each app the least access it needs. Most apps only send, so use a Send only key.

If this key leaks Send only Full access
Send mail from your verified domains Yes Yes
Read events, recipients, templates, and sent messages No Yes
See SMTP passwords and webhook secrets No Yes
Change clusters, domains, credentials, webhooks, and suppressions No Yes
  • Use a Full access key for setup scripts, the CLI, and MCP. Don't deploy one with your app.
  • Store keys in environment variables or a secrets manager. Don't commit them, log them, or put them in a URL.
  • Send from your server. Never put a key, even a Send only key, in browser or mobile code.
  • Create one key per app and environment, so you can delete one without breaking the others.
  • If a key leaks, delete it on API keys and create a new one. Deleting stops it straight away.

Delete a key

Click Delete next to the key on API keys. Anything using it stops working straight away.

Next steps