Quickstart

This page gets you from an authenticated partner admin session to a successful API call against the 4D nonprod environment.

1. Issue an organization API key

After signing in as a partner admin, issue an org_ key for your organization with POST /v1/api-keys. The session token below comes from the sign-in flow in Admin session tokens; if the admin holds seats on more than one organization, set the active organization first (step 4 there) and check organization_id on the response.

export API_BASE_URL="https://api.develop.fourdos.dev"
export ADMIN_TOKEN="<partner admin session token>"

curl -X POST "$API_BASE_URL/v1/api-keys" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Primary server"}'

The response includes raw_key, and that value is returned only once. It cannot be re-read from GET /v1/api-keys or a revoke response. Store it in your server-side secret store; if it is lost, revoke it and issue a replacement. An organization can have at most 10 enabled org_ keys. When that cap is reached, another issue request returns 409; revoke an unused key before creating a new one. There is no managed overlap window for replacement. Issue the new key, switch your service to it, then revoke the old key with DELETE /v1/api-keys/{keyId}. Revocation takes effect immediately.

The org_ key is a server-side secret. Never ship it in client code - for browser event tracking there is a separate publishable key type, covered in Trigger an event.

2. Set up your environment

All examples in these docs target the nonprod environment:

export API_KEY="org_...your key..."

3. Make your first call

Create (or attach) a member of your organization:

curl -X POST "$API_BASE_URL/v1/users" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-001" \
  -d '{
    "email": "ada.lovelace@example.com",
    "external_id": "cust-001",
    "display_name": "Ada L."
  }'

A 201 Created comes back with the full user record:

{
  "id": "0198f2b1-…",
  "email": "ada.lovelace@example.com",
  "display_name": "Ada L.",
  "status": "active",
  "wallet": { "status": "provisioning", "address": null },
  "membership": {
    "id": "…",
    "external_id": "cust-001",
    "role": "member",
    "status": "active",
    "joined_at": "2026-07-17T00:00:00.000Z"
  }
}

Run the same command again - same Idempotency-Key, same body - and you get the same user back with a 200 instead of a duplicate. Retries are safe by design.

Conventions to know

Wire format - JSON, snake_case field names.

Errors - every error shares one envelope:

{ "error": { "code": "VALIDATION_ERROR", "status": 422, "message": "…", "details": { } } }

code is the stable contract; message wording may change.

Idempotency - mutating endpoints that declare it accept an Idempotency-Key header. Replaying the same key with the same body returns the original response; the same key with a different body is rejected with 409 IDEMPOTENCY_CONFLICT.

Next steps

Authentication

The three credential types and when each applies.

Walkthrough: create a user

The full lifecycle: create, fetch, update, lock, remove.

Publish a private module

Issue credentials, publish an owned module, install it, and send an event.

Get started

Concepts

Walkthroughs

Content API

SDK

1. Issue an organization API key

2. Set up your environment

3. Make your first call

Conventions to know

Next steps

Authentication

Walkthrough: create a user

Publish a private module

​1. Issue an organization API key

​2. Set up your environment

​3. Make your first call

​Conventions to know

​Next steps

Authentication

Walkthrough: create a user

Publish a private module

1. Issue an organization API key

2. Set up your environment

3. Make your first call

Conventions to know

Next steps