Create a workspace API key

Mint an API key for a workspace with an organisation key and hand your customer its own credential — the full secret is returned once.

The workspace's plan key allowance applies (403 when used up) and the workspace must be active (409 workspace_not_active). The response's key field is the full secret and appears only in this response.

POST /v3/organisation/workspaces/{id}/keys

Body parameters

Parameter	Type	Required	Description
`name`	string	Required	Key name shown in the workspace's console and audit log.
`scope`	string	Optional	`full_access`, `send_only` or `read_only`. Default `full_access`. A customer that only sends needs `send_only`.
`env`	string	Optional	`live` or `test`. Test keys simulate delivery. Default `live`.
`verify_before_send`	boolean or null	Optional	Per-key verify-before-send override; `null` inherits the workspace setting.

Response (201)

json

{
  "id": "3f6b2a9e-1c4d-4e8f-9a0b-5c6d7e8f9a0b",
  "name": "Acme EU production",
  "prefix": "afn_live_pK7d",
  "scope": "send_only",
  "env": "live",
  "verify_before_send": null,
  "test_outcomes": null,
  "ip_allowlist": [],
  "last_used_at": null,
  "created_at": "2026-10-29T10:05:00Z",
  "key": "afn_live_pK7dXXXXXXXXXXXXXXXX"
}

Responses

Status	Description
`201`	Created. The new key — `key` is the full secret, shown only here.
`400`	Validation error.
`401`	Missing or invalid organisation key — workspace keys (`afn_live_` / `afn_test_`) are refused here by design.
`403`	`insufficient_scope` — the key lacks `keys:write` — or `ip_not_allowed`. Or the workspace's key allowance is used up.
`404`	No workspace with this id in your organisation (ids of other organisations are never revealed).
`409`	The workspace is archived or suspended.

Code examples

cURL

curl -X POST https://api.wemail.io/v3/organisation/workspaces/9d2f6c1e-4b3a-4e7d-8a1f-0c5b7e9d2a64/keys \
  -H "Authorization: Bearer afn_org_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme EU production",
    "scope": "send_only",
    "env": "live"
  }'

Node.js

const res = await fetch("https://api.wemail.io/v3/organisation/workspaces/9d2f6c1e-4b3a-4e7d-8a1f-0c5b7e9d2a64/keys", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.WEMAIL_ORG_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({"name": "Acme EU production", "scope": "send_only", "env": "live"}),
});
console.log(await res.json());

Python

import os, requests

res = requests.post(
    "https://api.wemail.io/v3/organisation/workspaces/9d2f6c1e-4b3a-4e7d-8a1f-0c5b7e9d2a64/keys",
    headers={"Authorization": "Bearer " + os.environ["WEMAIL_ORG_KEY"]},
    json={"name": "Acme EU production", "scope": "send_only", "env": "live"},
)
print(res.json())

ResponseExample response

{
  "id": "3f6b2a9e-1c4d-4e8f-9a0b-5c6d7e8f9a0b",
  "name": "Acme EU production",
  "prefix": "afn_live_pK7d",
  "scope": "send_only",
  "env": "live",
  "verify_before_send": null,
  "test_outcomes": null,
  "ip_allowlist": [],
  "last_used_at": null,
  "created_at": "2026-10-29T10:05:00Z",
  "key": "afn_live_pK7dXXXXXXXXXXXXXXXX"
}