Access: credentials, roles and permissions
Who can do what in a project: organization admins, roles and their permissions, each kind of credential, and what each may do in live.
Everything that changes a Domino project goes through a credential: a person's Console session, a key for an app or an agent, or a sign-in the CLI saved. What a credential may do depends on three things:
- Who it acts for. A person's credentials carry that person's roles. A key that no person owns carries only the permissions it was given.
- Its own limits. Most keys work in one project and one environment, and some kinds can never do certain things, whatever their permissions say.
- The environment. Live, where your real members are, accepts fewer changes than test. See what each credential may do in live.
Domino checks all three on every request, whichever tool sends it. Hiding a button in Console is never what stops an action.
Organization admins and project roles
People join your organization through Console, which uses Clerk for accounts and invitations. Each person is either an organization admin or a member.
- Organization admins hold every permission in every project, in test and live, without being granted anything. Only they manage the team's access, service and automation keys, app login keys, and the project itself: its name, deletion and transfer.
- Members can do nothing in a project until an admin grants them a role there, in Settings → Team.
A member can hold several roles in a project:
| Role | What it's for | Permissions |
|---|---|---|
| Editor | Publish quests, manage stock and points, and send tracker records and enroll members from your backend | Read, Publish, Inventory, Points, Ingest, Enroll, Dashboards |
| Reviewer | Review evidence and retry attempts | Read, Review, Dashboards |
| Staff | Confirm quests and hand over rewards | Read, Confirm, Handover, Dashboards |
| Viewer (experimental) | See the project's dashboards and nothing else: no members, evidence or settings. For a sponsor or client | Dashboards |
Permissions
| Permission | Allows |
|---|---|
| Read | Looking up the project: quests, members, progress, balances and analytics |
| Publish | Changing what the program is in test, preparing promotions, approving them in Console, and running day-to-day controls such as pausing a quest |
| Review | Deciding submissions and retrying attempts |
| Confirm | Confirming that a member completed a quest, such as checking them in at an event |
| Handover | Handing over rewards that members collect in person, and correcting those handovers |
| Inventory | Managing offers and stock |
| Points | Awarding, spending and correcting points |
| Ingest | Sending records to custom trackers |
| Enroll | Enrolling members in quests and campaigns from your server, which vouches for their consent |
| Dashboards | Reading the project's dashboards, which show totals and never an individual member. Read includes it, and no key holds it on its own |
| Access | Administering access. Only organization admins hold it: no role includes it, and no key can hold it |
Grants are per environment
An admin chooses, for each member, the roles and whether they apply in test, live or both. The same roles apply in each environment chosen. A grant can also have an end date: after it, the grant gives nothing, and Settings → Team shows it as Expired until an admin changes it. A member granted Editor in test only can build and try quests, and can neither read nor change anything in live.
Changes to a grant, and removing someone from the organization, take effect on that person's next request, for every credential that acts for them.
Kinds of credentials
| Credential | Who gets it, and how | What it acts as, and where |
|---|---|---|
| Console session | Anyone who signs in to Console | That person, in any project and environment their roles reach |
Personal API key, ak_… | Anyone with a role in the project other than Viewer alone, in Settings → API keys, or domino tokens create for a test key | Its owner, with the permissions chosen for it, in one project and one environment |
CLI session, dc_… | domino login, approved in Console | That person, in any project their roles reach, with the CLI's limits |
Playground session, dc_… | Starting a Playground | That person, in its one project and environment |
AI assistant connection, oat_… | Connecting an AI assistant and signing in | That person, in any project their roles reach, with the CLI's limits and no changes in live |
Service key, dsk_… | An organization admin, in Settings → API keys | An app's own backend, in one project and one environment |
Automation key, dak_… | An organization admin, in Settings → API keys | A headless agent or CI, in all of the organization's projects or chosen ones, changing test only |
Hosted app key, dhk_… | Domino, for each hosted app server and domino dev | The hosted app's server, in its project: test for previews, staging and development, live for the live app |
App login key, di_… | An organization admin, in Settings → App login keys, which can save it straight into a hosted app's secrets | Your server, signing members in with your app's login for one project and environment; it calls nothing else |
The first five act for a person and stop working when that person leaves the organization. Service, automation, hosted app and app login keys belong to no person.
A domino login request waits 15 minutes for approval. Console's approval page shows when it was made, the country it came from and the CLI version and system that sent it. Approve only a request your own terminal just made: the session it creates acts as you. Connecting a service through its own sign-in, such as Klaviyo, is finished in Console by the person who started it, so a credential that belongs to no person can't start one.
Personal API keys
A personal key acts as you, so it can never do more than you can. You choose its project, its environment and a subset of your permissions in them when you create it, and it can't hold Access. A key from Console expires after 30 days; a test key from domino tokens create --days lasts 1 to 90. It stops working when you leave the organization, and loses any permission you lose.
A key holding Ingest can be limited further, to sending records to chosen custom trackers only. Use one for an indexer or a partner's server that should not reach anything else.
You can create a test key from the CLI. A live key is created in Console only.
Service and automation keys
These belong to no person, so they keep working when the admin who made them leaves. Each has the permissions chosen when it was created, never Access, and never expires unless an expiry was chosen. An admin can rotate a key by adding a new secret, then revoking the old one once nothing uses it, or revoke the whole key at once.
- A service key is for an app's own backend, outside Domino hosting: awarding points, sending tracker records, qualifying referrals. It works in one project and environment. See connect your app.
- An automation key is for a coding agent or CI with nobody there to approve
domino login. It reaches all of the organization's projects or chosen ones, holds at most Read, Publish, Inventory, Points, Ingest and Enroll, and changes nothing in live. See run an agent without signing in.
Hosted app keys
Domino gives every staged and live Worker app, and the dev server domino dev starts, its own key, so nobody pastes a credential into a hosted app. It holds exactly Read, Points and Ingest, in its own project and environment. A domino dev key ends when the dev server stops, or after 12 hours. See call the management API from your server.
What keys and the CLI don't do
- Administer access. Grants, the team and the project's name, deletion and transfer take an organization admin's Console session. CLI sessions and AI assistant connections are refused too.
- Create another credential. Only an admin's Console session creates service, automation and app login keys. Personal keys are created by their owner in Console, or as test keys from a CLI session; no key creates or revokes one.
- Act as test members. Service and hosted app keys are an app's own server, so they can't create test members or act as them. Console sessions, personal keys, CLI and Playground sessions, AI assistant connections and automation keys can, in test, when they act with Publish.
What each credential may do in live
Live accepts two kinds of change, as test and live explains. Definitions (quests, rewards, point ledgers, code and the rest of what your program is) reach live only through a promotion a person approves in Console. Operations (pausing a quest, reviewing a submission, correcting points) happen in live directly, under the credential's permissions.
No credential changes definitions in live, Console included, and new code reaches live only through a promotion: make the change in test and promote it. For everything else:
| Credential | Decide a promotion | Day-to-day operations |
|---|---|---|
| Console session | Yes, with Publish | Yes |
| Personal API key for live | No | Yes, with its permissions |
| Service key for live | No | Yes, with its permissions |
| Hosted app key of the live app | No | Read, points and tracker records |
| CLI session | No | Only the list below |
| AI assistant connection | No | None: reads only |
| Automation key | No | None: reads only |
Every credential that reaches live and holds Read can look things up there. A key or session fixed to test can't read live.
The CLI in live
A domino login session may make only these changes in live:
- Prepare a promotion with the deprecated
domino deploy --promote(domino promotedoes the same from test), and roll back a promotion. A person still approves each promotion in Console. - Preview catalog changes and submit them for review.
- Set app secrets, custom domains and plugin connections, which belong to each environment and never move with a promotion.
- Upload images a preview needs.
- Prepare, check, cancel, stop and revert a member import. Only Console applies one in live.
- Revoke your personal keys. The CLI creates and changes test keys only.
For anything else in live, use Console, or create a live personal key there for your script.
Actions only Console takes in live
Some live actions need a person signed in to Console, whatever keys exist:
- Approving or rejecting a promotion.
- Applying a member import.
- Creating a personal key for live, or changing which trackers one may send to.
Deleting a whole quest's evidence at once in live takes an organization admin, through Console or their own personal key, or a service key holding Review, because it can't be undone. Deleting one attempt's evidence stays a reviewer's action.