Authentication

The v1 public API uses bearer-style personal API keys. Keys are created in-app, shown in full only once, and stored as hashed secrets on the backend.

API keys

• Create keys from the mobile app’s API Access screen.
• Keys are lane-local and scoped to the account owner.
• The plaintext value is only shown once at creation time.

Bearer auth

Send the key as a bearer token on every request:

  curl "https://api.duitmyself.app/v1/accounts" \
-H "Authorization: Bearer key_..."

Required write headers

POST and PATCH requests require an Idempotency-Key header. Reusing the same key with the same request body replays the stored response. Reusing the same key with a different body returns a conflict error.

  curl -X POST "https://api.duitmyself.app/v1/transactions" \
-H "Authorization: Bearer key_..." \
-H "Idempotency-Key: txn-demo-001" \
-H "Content-Type: application/json" \
-d '{
  "accountId": "acct_...",
  "amount": 12.5,
  "date": "2026-04-13"
}'

Response metadata

Every response includes:

• X-Request-Id
• X-RateLimit-Limit-Minute
• X-RateLimit-Remaining-Minute
• X-RateLimit-Reset-Minute
• X-RateLimit-Limit-Day
• X-RateLimit-Remaining-Day
• X-RateLimit-Reset-Day

When the API returns 429 rate_limit_exceeded, it also includes Retry-After.

Scopes

Keys store route scopes such as:

• me:read
• accounts:read
• accounts:write
• transactions:read
• transactions:write
• categories:read
• categories:write
• payees:read
• payees:write

v1 public behavior remains self-only, but the underlying auth context is already structured around principal and subject separation for future delegated access without replacing the route contract.

Key scope

Keys only authorize requests for the account owner and only for the scopes attached to that key.