Access
Configure how clients authenticate to your project — API keys, trusted issuers, and sessions
An auth method is a configured way for a client to authenticate to the Lunogram APIs. Every auth method is bound to a single project and only grants access to that project's data. Manage them under Settings → Access.
There are three types:
API key
A Lunogram-issued private key (sk_) your backend sends as a Bearer token. Backend-only — never ship it in client-side code.
Trusted issuer
Validate JWTs minted by your own identity provider (Bring Your Own IdP). No key to distribute.
Session
Mint short-lived, user-scoped tokens from your backend for use in the browser.
The authorization an auth method grants — its role (and optional custom permission set) — is independent of how it authenticates, so the roles below apply to every type.
API keys
API keys are private (sk_) and backend-only. Your server sends one as a Bearer token, with full access per its role. A key presented from a browser — a request carrying an Origin header — is rejected, so a key can never be safely embedded in client-side code. For browser and mobile clients, use a trusted issuer or a session instead.
The full key is shown once, right after creation — copy it then. Afterwards only a short prefix is displayed; the secret is stored hashed and cannot be recovered. If you lose it, delete the key and create a new one.
Trusted issuers (Bring Your Own IdP)
A trusted issuer lets your end users call the Client API directly with a JWT minted by your own identity provider — no Lunogram key in the browser.
Configure it with either a JWKS URL or a PEM public certificate, the expected issuer (iss), an optional audience (aud), and which claim carries the user id (subject claim, defaults to sub). Lunogram verifies each token's signature (RS/ES/PS algorithms only — HMAC and none are rejected), enforces exp/iss/aud, and resolves the subject to a user.
By default a request authenticated this way reads and writes only its own user's data — see Data access.
Sessions
A session auth method lets your backend mint a short-lived, user-scoped token that the browser then uses against the Client API.
Your backend calls POST /api/client/sessions with an API key, naming the session method and the user_id. Lunogram returns a token whose lifetime and permissions come from the session policy. Like trusted-issuer requests, a session defaults to its own user's data — see Data access.
Data access
Because trusted issuers and sessions carry a verified subject (the end user behind the token), they also choose a data boundary — whose records a request may touch, within its role:
| Data access | Behaviour |
|---|---|
| Own data only (default) | The request is bound to the verified subject. Any client-supplied identifier is ignored, so the caller can only ever read and write its own records. Use this for end-user apps. |
| All data | The verified subject authenticates the request, but it acts across every user's records (like a backend key). Use this for an internal or support tool that signs in through your IdP yet needs to see other users' data. |
API keys have no verified subject, so they always act across all data; their reach is bounded by their role instead.
Create constraints
A create grant — events:create, subscriptions:create, or scheduled:create — can be narrowed to an allow-list of names, so the client may only create the instances you name (for example, only emit the event names you list). The constraint is set per auth method, alongside its permissions, and travels with the credential — so it applies to every type: API key, trusted issuer, or session.
| Constraint | Behaviour |
|---|---|
| Not set (default) | The client may create any instance the grant allows. |
| Configured | Only the listed names are accepted; any other is rejected with 403. |
There is no "allow nothing" state: to deny creation entirely, don't grant create. Enforcement is server-side and fails closed. Configure it under Settings → Access on the auth method, or through the Management API via grant_constraints.
Roles
Every auth method is assigned a role that determines what it can access. Roles are additive — each higher level includes the permissions below it.
Write-only access designed for client-side ingestion (events and user data).
| Permission | |
|---|---|
| Create & update users, events, and organizations | ✅ |
| Read any resource | ❌ |
| Modify campaigns, journeys, or settings | ❌ |
Read-only access across all project resources. Ideal for dashboards and reporting.
| Permission | |
|---|---|
| View users, campaigns, journeys, templates | ✅ |
| View events, lists, tags, and documents | ✅ |
| Create, update, or delete any resource | ❌ |
Full content management. Includes everything in Support and Client.
| Permission | |
|---|---|
| Everything in Support and Client | ✅ |
| Create & manage campaigns, templates, journeys | ✅ |
| Manage lists, tags, documents, locales, and actions | ✅ |
| Manage providers / destructive operations | ❌ |
Full project access including providers and destructive operations.
| Permission | |
|---|---|
| Everything in Editor | ✅ |
| Manage providers and integrations | ✅ |
| Delete subscriptions, actions, and organizations | ✅ |
Admin grants unrestricted access. Only ever use it from your backend, never in client-side code.
Which should I use?
Frontend app, logged-in users
A trusted issuer (reuse your IdP's JWTs) or sessions (mint from your backend) — each user reads/writes only their own data.
Frontend app, anonymous tracking
Mint a session from your backend for the visitor (assign a device or anonymous id); the browser then ingests events and users with that short-lived token. Browsers cannot use an embeddable key.
Backend integration
An API key (sk_) with Editor or Admin, kept in environment variables.
Analytics / reporting
An API key with the Support (read-only) role.