An account is the top-level tenant. All resources (sources, destinations, events, etc.) are scoped to an account. Account creation is intentionally open for MVP bootstrapping — no API key required.

Create account

Creates a new account and returns a bootstrap API key.

POST /v1/accounts

Authentication: None

Request body

Field	Type	Required	Description
name	string	Yes	Human-readable account name

Response 201 Created

{
  "data": {
    "account": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Acme Corp",
      "plan": "free",
      "created_at": "2024-01-15T10:00:00Z"
    },
    "api_key": {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "default",
      "key_prefix": "hk_a1b2",
      "plain_key": "hk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
      "created_at": "2024-01-15T10:00:00Z"
    }
  }
}

Save plain_key immediately

The full API key is returned only once. After this response, only the key_prefix (e.g. hk_a1b2) is stored for display purposes.

Errors

Status	Error	Cause
400	name is required	Request body missing or name is empty
500	Internal error	Database error

curl example

curl -s -X POST http://localhost:8080/v1/accounts \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp"}' | jq .

Store the key:

export API_KEY=$(curl -s -X POST http://localhost:8080/v1/accounts \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp"}' | jq -r '.data.api_key.plain_key')

echo "API Key: $API_KEY"

Previous pageOverview

Next pageAPI Keys