Provision and fund a customer

Six calls to a funded, capped, observable customer — create a child org, mint its key, allocate credits, set spend limits, and subscribe the firehose.

View as Markdown

This is the linear quickstart: run these calls in order and you'll have a customer modeled as an isolated child organization — funded, capped, with its own API key, and feeding events into your webhook. Every call uses your parent (org:admin) key. For the per-operation reference (suspend/resume, offboard, working inside a child via the header), see Manage customers with sub-organizations.

The running example onboards Acme Coffee. You'll need a parent key with the org:admin scope. Send a fresh Idempotency-Key on every call.

1 · Create the child org

curl -X POST https://api.layers.com/v1/organizations \
  -H "Authorization: Bearer $PARENT_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Coffee", "metadata": { "externalId": "acme-coffee" } }'

Keep id from the response — org_d4e5f6a7-…. It's the :orgId in every call below.

2 · Mint the customer's API key

curl -X POST https://api.layers.com/v1/organizations/org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80/api-keys \
  -H "Authorization: Bearer $PARENT_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "acme-integration", "scopes": ["content:read", "content:write"] }'

Grab secret — it's shown once. Scopes must be a subset of your parent key's; org:admin is never delegable.

3 · Allocate credits

curl -X POST https://api.layers.com/v1/organizations/org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80/credits/allocate \
  -H "Authorization: Bearer $PARENT_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "credits": 5000 }'

Moves 5,000 credits from your parent wallet into Acme's. The response returns the transfer id (txn_-prefixed — your reconciliation handle) alongside the child's post-allocation balance and available. The Idempotency-Key header is required on this route.

4 · Set the cap + auto-refill

curl -X PATCH https://api.layers.com/v1/organizations/org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80/credit-config \
  -H "Authorization: Bearer $PARENT_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "monthlyCreditCap": 5000, "refillThreshold": 1000, "refillAmount": 2000 }'

Caps Acme at 5,000 credits/month and tops them up 2,000 whenever available drops below 1,000. Response confirms config.autoRefillEnabled: true. (Refill is both-or-neither — set both refill fields or neither.)

curl -X POST https://api.layers.com/v1/webhook-endpoints \
  -H "Authorization: Bearer $PARENT_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://quinns-crm.example.com/layers/webhooks",
    "events": ["content.generated", "post.published"],
    "scope": "all_children"
  }'

One endpoint, every child's events. Store the returned signingSecret (shown once). Each delivery's data.organizationId tells you which customer it's for.

6 · Verify

curl https://api.layers.com/v1/organizations/org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80 \
  -H "Authorization: Bearer $PARENT_KEY"

The summary confirms the whole setup in one read: balance / available (funded), and creditConfig (monthlyCreditCap: 5000, autoRefillEnabled: true). Acme is now a funded, capped, observable customer authenticating with its own key.

What you have now

An isolated child org (org_d4e5f6a7-…) — its projects, wallet, and audit trail are invisible to your other customers.
A dedicated child key Acme's integration uses directly (never your parent key).
5,000 credits allocated, a 5,000/month cap, and 2,000 auto-refill below 1,000.
One parent webhook endpoint receiving Acme's events, attributed by data.organizationId.

Manage customers with sub-organizations — suspend/resume, offboard (archive reclaims unspent credits), and working inside a child with the X-Layers-Organization header.
Credits concept — balance vs available, allocation, caps, and auto-refill in depth.
Migrate existing projects — already have flat projects? Move them under child orgs in one call.