First API Integration

Goal

Create a workspace API key and call a public integration endpoint using that key.

Step 1: Login (JWT)

curl -sS -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "founder@zutax.test",
    "password": "ChangeMe123!"
  }'

Store access_token from the response.

Step 2: Get Default Context IDs

curl -sS http://localhost:8000/api/v1/workspaces/default-context \
  -H "Authorization: Bearer <access_token>"

Store:

• TENANT_ID
• WORKSPACE_ID

Step 3: Create API Key (JWT)

curl -sS -X POST \
  "http://localhost:8000/api/v1/tenants/${TENANT_ID}/workspaces/${WORKSPACE_ID}/integrations/api-keys" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "erp-sync-prod",
    "description": "ERP nightly sync",
    "scopes": ["invoice:read", "party:read", "report:read"],
    "expires_at": "2027-01-01T00:00:00Z"
  }'

Save raw_key immediately. It is returned once.

Step 4: Call Public Endpoint (API Key)

curl -sS \
  "http://localhost:8000/api/v1/tenants/${TENANT_ID}/workspaces/${WORKSPACE_ID}/invoices?page=1&page_size=20" \
  -H "X-API-Key: <raw_key>"

This endpoint is public-audience and supports API key auth.

Step 5: Verify Scope Enforcement

Try an operation outside the key scope and confirm 403 response.

If you need write operations, issue a separate key with narrow write scopes.