Concepts
A few ideas explain most of how Dianthan behaves. Read this once and the rest of the API becomes predictable.
Accounts and apps
Your account is you, or your team. It holds billing, the dashboard and any number of apps.
An app is one product. Every piece of app data (records, files, logs, subscriptions, flags, jobs) carries the app's ID, and every query filters by it. One app can never read another app's data, even when both belong to you. A test suite checks this on every release.
App IDs look like app_8Jq2…. Every ID in Dianthan has a prefix that names its type: usr_ for users, org_ for organizations, sub_ for subscriptions, and so on. If you find an ID in a log, the prefix tells you what it refers to.
Users and memberships
A user is a person. They have one identity across Dianthan, so signing in to a second app of yours doesn't create a second person.
A membership is what that person is inside one app: a customer, a member or an admin. Customers can use self-service routes only, such as their own profile, entitlements and billing portal. They can never list other users or read app-wide data.
Each app chooses whether sign-up is open (anyone who signs in becomes a customer) or closed (only people you invite or create from your server).
Organizations
An organization groups users who work together. It has members, roles, invitations, its own API keys and, optionally, single sign-on. You can bill an organization instead of a person, and its entitlements then apply to every member.
The three ways to authenticate
| Who | Credential | Sent as |
|---|---|---|
| A person using your app | Access token from a sign-in | Authorization: Bearer <jwt> |
| Your server | App key (dn_live_…) | X-API-Key and X-App-Id headers |
| You, in the dashboard or CLI | Your own session or a personal key | Authorization: Bearer <jwt> |
Server keys act for the whole app. Keep them on your server and pass the visitor's IP in X-Client-IP, so rate limits apply to the visitor and not to your server.
Systems
A system is one area of the API: identity, billing, metering, data, messaging, automation, observe or flags. Systems are switched on per app. A request to a system that's switched off returns 403 module_disabled and a link to switch it on.
Systems work on their own and share three things:
- One identity. Every system knows the same users and organizations.
- One event stream. Changes in any system appear in the app's event feed and can trigger webhooks.
- One audit log. Every change records who made it, using which credential, and from where.
Environments
Use separate apps for production and development (for example fieldnotes and fieldnotes-dev). They cost nothing extra on paid plans, and keeping them apart means a development key can never touch production data.