Quickstart

This page gets you from zero to a successful authenticated call against the 4D nonprod environment.

1. Get your API key

Your organization’s admin obtains an API key during partner onboarding (or from the 4D team directly). Keys are prefixed org_ and are scoped to your organization - every call you make operates inside your own tenant, enforced at the database layer.

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_BASE_URL="https://api.develop.fourdos.dev"
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.

Get started

Concepts

Walkthroughs

SDK

1. Get your API key

2. Set up your environment

3. Make your first call

Conventions to know

Next steps

Authentication

Walkthrough: create a user

​1. Get your API key

​2. Set up your environment

​3. Make your first call

​Conventions to know

​Next steps

Authentication

Walkthrough: create a user

1. Get your API key

2. Set up your environment

3. Make your first call

Conventions to know

Next steps