Issue a free API key and tenant

POST

/v1/keys

POST

/v1/keys

curl -X POST https://api.withwrit.com/v1/keys \
     -H "Content-Type: application/json" \
     -d '{
  "email": "ops@example.com",
  "tenantName": "Acme support"
}'

{
  "apiKey": "writ_7hK2xQ9mZp4v...",
  "defaultPolicy": {
    "admit": "require_grant",
    "prescribe": "require_grant",
    "provision": "require_grant",
    "refund": "require_grant",
    "verify": "require_grant",
    "verify_human": "require_grant"
  },
  "email": "ops@example.com",
  "monthlyChecks": 10000,
  "plan": "free",
  "principalId": "prn_9d2f4a1b2c3d",
  "sponsorToken": "writ_sp_9dKx2mQv...",
  "sponsorTokenNote": "Shown once and never recoverable. The sponsor token approves grants and revokes principals for this tenant. Store it somewhere safe.",
  "tenantId": "ten_3fa8b91c2d44"
}

No auth. This is how a tenant is born: POST an email and get back an API key (writ_...), a tenant ID, and the tenant’s default verb policy. The first key issued for an email creates a new tenant and also returns that tenant’s sponsor token (writ_sp_...) — shown exactly once, never recoverable. The sponsor token is the human half of the credential model: it mints grants and operates the kill switch. Pass inviteCode to join an existing tenant instead of creating your own — joining members do not receive the sponsor token.

Rate-limited to 10 keys per hour per client IP. Without this, the free monthly check quota would be trivially bypassed by minting keys.

Pass principal_id to issue the key to an identity-directory principal (see Principals); the id must belong to a live principal in the tenant. Without one, the key lands on the tenant’s default principal, created on first use.

Request

This endpoint expects an object.

emailstringRequired

Contact email for the key. The first key for an email creates the tenant.

tenantNamestringOptional

Display name for a newly created tenant.

inviteCodestringOptional

Team invite code (writ_inv_…) to join an existing tenant instead of creating one.

principal_idstringOptional

Identity-directory principal (prn_…) the key is issued to. Must be a live principal in the tenant.

Response

apiKey, tenantId, sponsorToken (first key of a tenant only), defaultPolicy, monthlyChecks (10,000 free receipts per tenant per month)

Errors

400

Bad Request Error

429

Too Many Requests Error