POST
/
v1
/
tenants
curl https://api.geldstuck.com/v1/tenants \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Escrow",
    "metadata": { "region": "eu-west" }
  }'

{
  "tenantId": "tnt_01HX3Z8MQW...",
  "name": "Acme Escrow",
  "status": "active",
  "accessKey": "pk_live_51H...",
  "secretKey": "sk_live_51H...",
  "webhookSecret": "whsec_xS...",
  "metadata": { "region": "eu-west" },
  "createdAt": "2026-04-22T09:12:44.000Z"
}
Creates a new tenant and generates its first key pair and webhook signing secret. This endpoint requires an admin credential (not a tenant API key). The secretKey and webhookSecret are returned once - store them immediately.

​
Body

​
name
string
required
Human-readable tenant name. Must be unique per Geldstuck account.
​
metadata
object
Arbitrary key/value pairs (up to 20 keys, 500 chars each) stored alongside the tenant. Returned on retrieval.

​
Returns

A tenant object with one-time credential fields.
​
tenantId
string
ULID, e.g. tnt_01HX3Z8MQW...
​
name
string
​
status
string
active, suspended, or disabled.
​
accessKey
string
Publishable key. Safe to log.
​
secretKey
string
Secret key. Shown once.
​
webhookSecret
string
HMAC secret for webhook signatures. Shown once.
​
createdAt
string
ISO 8601 timestamp.
curl https://api.geldstuck.com/v1/tenants \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Escrow",
    "metadata": { "region": "eu-west" }
  }'

{
  "tenantId": "tnt_01HX3Z8MQW...",
  "name": "Acme Escrow",
  "status": "active",
  "accessKey": "pk_live_51H...",
  "secretKey": "sk_live_51H...",
  "webhookSecret": "whsec_xS...",
  "metadata": { "region": "eu-west" },
  "createdAt": "2026-04-22T09:12:44.000Z"
}