Doppler Security Guide: Tokens, Roles, OIDC Identities, Logs and Leak Response

A Doppler workplace holds the secrets that applications, pipelines and AI agents use to reach databases, clouds and third-party APIs, so a long-lived token in the wrong place, an over-broad role or a config open to the whole internet turns the secrets manager into the shortest path to everything else. This guide explains how to run Doppler securely, using Doppler's own documentation and its open-source CLI as the source for every product detail. It covers the project, environment and config model, the seven token types and their prefixes, service tokens, service accounts and OIDC service account identities, workplace and project roles, Trusted IPs, secret access logs and activity logs, CLI fallback files, a hardening baseline and what to do when a token leaks. It is written for platform engineers, security engineers and identity teams who run Doppler or are taking over a workplace. For the general discipline see the Secrets Management Guide; for how machine access compares across secrets platforms see the Akeyless, Doppler and 1Password Machine Access Guide.

Key takeaways

• The config is the unit of access. Secrets live in configs inside environments inside projects, and the narrowest machine credential, a service token, reaches exactly one config, read-only unless you grant write.
• Every token announces its type. Seven documented prefixes, from dp.st. for service tokens to dp.pt. for personal tokens, tell a responder the owner and likely reach of a leaked value before any lookup.
• Federation removes the stored machine secret. Service account identities exchange an OIDC token from a CI system or cluster for a short-lived dp.said. token, so pipelines need no long-lived Doppler credential.
• Personal and CLI tokens do not belong in production. Doppler states they carry write access with the creating account's permissions and should not be used in live environments.
• Two logs answer two questions. Secret access logs show which actor read which secret and when; activity logs show who changed tokens, roles, members, secrets and integrations, and can be streamed to a SIEM.

How Doppler organises secrets

A Doppler workplace contains projects, usually one per application or service. Each project has environments, and Doppler's branch config documentation names three default root configs: dev, stg and prd. A root config is the base for its environment, described by Doppler as the root from which all future configs branch.

A branch config is created from a root config and takes the environment name as a prefix, for example dev_stripe_billing. It inherits changes from its root and can hold its own overrides on top. Doppler lists typical uses as a dedicated config per cloud deployment, feature work that needs secrets not yet released, and sharing a config with teammates by name. On development environments, personal configs give each user with write access a private branch, visible only to that user.

This structure is the main security strength of the model, because it lines up access boundaries with deployment boundaries:

• Environment separation: production secrets sit in prd and its branches, so roles and tokens can grant development access without touching production.
• Config scoping: a service token is bound to one config, so a separate config per deployment target means a separate, independently revocable credential per target.
• Change history: config logs are commit-style and can be rolled back when versioning and rollbacks are enabled, which turns an unwanted secret change into a reversible event.
• Inheritance with care: a branch inherits from its root, so a value added to the prd root reaches every prd_ branch. Keep secrets that only one target needs in that target's branch.

Doppler token types and prefixes

Doppler's token formats reference states that every auth token shares the same random body of 40 to 44 alphanumeric characters and differs only by prefix. A service token may also carry an optional environment segment of 2 to 35 lowercase letters, digits, hyphens or underscores, such as dp.st.dev.. The prefixes make Doppler tokens easy to match in secret scanners and log searches, and they are the first triage signal in an incident.

The environment segment is a useful hint, not a guarantee: dp.st.prd. in a public repository should be treated as a production incident at once, but a token without a segment may still belong to a production config. The activity log schema confirms create, roll and revoke events exist for personal, CLI, SCIM, audit and service account tokens, and create and delete events for config service tokens, so every token lifecycle change can be audited.

Machine access: service tokens, service accounts and identities

Doppler offers three machine credential patterns. Choosing well between them is the single biggest security decision in a Doppler rollout.

Service tokens

Doppler's service token page describes a token that gives an application access to one config within one project, following least privilege. Tokens are read-only by default; write access is an explicit option in the dashboard. A token is shown only once, at creation. An expiration time can be set, after which the token is deleted automatically, and the CLI can create ephemeral tokens with --max-age, for example a token that lives for one minute for a single job. Revocation from the config's Access tab or with doppler configs tokens revoke -p PROJECT -c CONFIG is immediate and cannot be undone.

Service accounts

A service account combines a workplace role, project access and any number of tokens. Unlike a service token it can span several projects and hold workplace-level permissions. Doppler documents that a new service account has no workplace role and no project access, so it cannot do anything until access is granted. Only Admins, or users with the Manage Service Accounts permission, can manage them. Tokens are shown once, and can be rolled or deleted from the token menu; the service accounts page does not describe token expiry, so plan rolling on your own schedule.

Service account identities (OIDC)

Service account identities let a workload authenticate with an OIDC token it already holds. Doppler names GitHub, GitLab and CircleCI, the Doppler Kubernetes Operator and the GitHub Secrets Fetch Action, and also accepts a custom discovery URL. The workload posts its OIDC token and the identity ID to https://api.doppler.com/v3/auth/oidc, or runs doppler oidc login --scope=. --identity=<id> --token=$OIDC_TOKEN, and receives a short-lived API token with an expires_at value. Doppler says these tokens expire quickly and should not be persisted, and doppler oidc logout revokes the token when the job ends.

• Required claims: aud and sub must be configured; custom claims such as GitLab's environment can be added.
• Matching: each claim can accept several values and one must match for every configured claim; nested claims can be checked with JSON Pointer keys.
• Wildcards: Doppler recommends avoiding them where possible, because exact-match rules are simpler to configure and reason about. A wildcard subject can let any branch or any repository in an organisation assume the identity.

This is the pattern the Secrets Zero Problem Guide describes in general terms: the workload proves who it is with a credential its platform already issues, so no Doppler secret has to be stored in CI variables. See the Workload Identity Federation Guide for claim design.

Availability: Doppler documents service accounts, service account identities, Trusted IPs and role-based project access as Team and Enterprise plan features. Access log history also depends on the plan.

Workplace and project roles

People and service accounts get access through two layers. The workplace role sets what an actor can do across the workplace; project roles set what it can do inside each project, per environment. Doppler's project permissions page lists four built-in project roles and allows custom roles:

• Workplace Owners and Admins: Doppler states they always have full access to every project and environment. Their personal and CLI tokens are therefore workplace-wide credentials. Keep few of them and delegate project administration through project Admin roles instead.
• Workplace Collaborators: need per-project, per-environment grants, which is the right default for most engineers.
• Effective permissions combine: an actor's rights in an environment are the union of direct roles, group roles and any inherited workplace role, so review group membership as part of every access review.
• New environments: roles without Access All Configs cover only the environments selected, so adding an environment needs a deliberate grant; roles with it, such as Admin, extend automatically.
• Automation: the API and Terraform both manage roles. Doppler warns that updating a member through the general member endpoint replaces all roles except the oldest, and that member and role-assignment Terraform resources should not be mixed for the same member. Both mistakes can silently widen or remove access.
• SCIM: a SCIM token can create users and change group membership, and groups carry project roles, so it is an identity administration credential.

Trusted IPs

Trusted IPs restrict which client addresses can use a config. Each config holds its own list of CIDR ranges, and only requests from within them can access the config through its API endpoints. Doppler's documentation is specific about the limits:

• Default open: new configs start with 0.0.0.0/0, which admits the public internet.
• Who manages them: the Trusted IPs page states only workplace Admins can manage them, while the project permissions page lists Trusted IPs among what a project Collaborator manages in its configs. Check in your own workplace who can change the list and alert on changes either way.
• Scope: they do not control which addresses can log in to the dashboard, and they apply only to the API endpoints tied to the config.

For production configs read by servers with stable egress addresses, replacing 0.0.0.0/0 with your egress ranges means a leaked service token is useless from anywhere else. Test on a staging config first, because removing the default without adding the right ranges blocks every consumer. Workloads with changing egress, such as hosted CI runners, are better served by OIDC identities than by wide IP ranges.

Secret access logs and activity logs

Secret access logs

For each secret, Doppler records the actor, the access method, and the first and most recent read. Actors include users, service tokens, personal tokens, CLI tokens and API, Terraform provider or Kubernetes Operator access via a token. Doppler counts an access whenever a request returns a payload containing the secret, whether or not the actor actually used it; responses without values, such as an Operator "no update" response, are not logged, a dashboard value is fetched only when a user clicks it, and secrets with blank values are not tracked. History spans all versions of a secret within the plan's limits, so export what you need early in an investigation.

Activity logs

Activity logs record workplace and config changes, link to commit-style config logs, and can be sent to AWS SQS, Datadog, Discord, a generic HTTPS endpoint, Microsoft Teams, Slack, Splunk and Sumo Logic. The event schema gives the names to alert on:

The actor field has a kind of user, serviceAccount, apiToken or bot. The schema does not document an IP address field, so network context has to come from your own egress and proxy logs and from Trusted IP enforcement.

Metrics that show the programme is working:

• Personal and CLI tokens found outside developer machines, in CI, servers or images (target: zero).
• Share of service tokens with an expiry, and share that are read-only.
• Production configs still allowing 0.0.0.0/0 in Trusted IPs.
• Share of CI and Kubernetes consumers on OIDC identities rather than stored tokens.
• Number of workplace Owners and Admins, reviewed quarterly.
• Time from token revocation to the last exposed secret rotated.

CLI fallback files

The Doppler CLI writes fetched secrets to an encrypted fallback file after each successful fetch, and reads from it if later connections fail. The service token page warns that a revoked token stops access to the latest secrets but the CLI can keep serving the last version it fetched from this file. The CLI source on GitHub shows the controls:

• Location: a fallback directory inside the CLI's configuration directory, which the CLI creates with mode 0700; --fallback sets a custom path.
• Encryption key: --passphrase or the DOPPLER_PASSPHRASE variable; otherwise the CLI computes a default passphrase from the current configuration. Set an explicit passphrase from a separate source where the host's configuration could be copied with the file.
• Behaviour flags: --no-fallback disables reading and writing the file (and implies --no-cache), --fallback-readonly stops it being modified, and --fallback-only (alias --offline) reads only from the file without contacting Doppler.
• Clean-up: doppler run clean deletes fallback files older than a maximum age (default 14 days), with --all to remove every file and --dry-run to preview.

The fallback is a resilience feature, and a useful one when the API is unreachable. The trade-off is an encrypted copy of secrets on disk. Decide per workload: keep it where availability matters most, disable it on short-lived or shared hosts, and run doppler run clean --all when decommissioning a host or after a leak.

Responding to a leaked Doppler token

A Doppler token is a bearer credential, and a leak is a leak of every secret it could read. Revoking the token is the first half of the response; rotating what it reached is the second. Leaks in build output are common: in ArtiPACKED, live CI and cloud tokens were found in public GitHub Actions artifacts and logs uploaded by well-known projects.

1. Classify: read the prefix and any environment segment from the table above; record where the value was found and the earliest possible exposure time.
2. Revoke: for a service token use the config's Access tab or doppler configs tokens revoke; for a service account token delete it, or roll it and deploy the new value at once if a consumer must keep working; for personal and CLI tokens revoke in the user's token settings. If you hold only the value, send it in a POST to https://api.doppler.com/v3/auth/revoke. Revocation is irreversible.
3. Clear fallback files: run doppler run clean --all on hosts that used the token, because the encrypted fallback can still serve the last secrets.
4. Scope: a service token reaches its one config; a service account reaches every config its roles grant; a personal or CLI token reaches everything that user can read, across projects; a SCIM token is an identity incident, so review users and groups first.
5. Investigate: use access logs to see which secrets the token actually read and when, and search activity logs for its actor across the window for secret updates, sharing, new tokens, service accounts, role changes and integration changes. Roll back unwanted secret changes from the config log.
6. Rotate downstream: rotate exposed secrets at their source (database passwords, cloud keys, API keys), update them in Doppler and let syncs propagate. Start with secrets the logs show were read, then the rest of the token's scope.
7. Remove the cause and close out: replace the leaked credential with an OIDC identity or a scoped, expiring service token, and record evidence with the Secrets Rotation Runbook Template.

If many tokens may be exposed at once, for example after a CI system or laptop fleet compromise, the event schema includes workplace.tokens.revoke.initiated and .completed for a workplace-wide token revocation. Confirm with Doppler how it works for your plan before you need it, because it will break every consumer at once. The general process is in the Leaked Credential Response Playbook.

Rolling out a hardening baseline

1. Inventory: list projects, configs, service tokens per config, service accounts with their roles, identities with their claims, and workplace Owners and Admins. Ask each team where personal or CLI tokens are used outside laptops.
2. Set structure: one project per application, separate configs per deployment target, production-only secrets kept in prd branches rather than shared roots.
3. Tighten roles: make Collaborator the default workplace role, grant project roles per environment, keep project Admin small, and add a custom role with Approve Change Requests on prd where change review is needed.
4. Pilot federation: move one CI pipeline to a service account identity with exact-match aud and sub claims, run old and new side by side, then revoke the old token once access logs show only the new actor.
5. Replace personal and CLI tokens: one consumer at a time, create the new credential, deploy, confirm reads succeed, then revoke the old token.
6. Restrict Trusted IPs: on staging first, then production configs with stable egress.
7. Stream and alert: send activity logs to the SIEM and alert on the events in the table above.
8. Roll back safely: keep the previous credential valid but monitored until consumers confirm; for a bad role or Trusted IP change, restore the previous value and retry; for a bad secret change, roll back from the config log.

Small and large organisations: on plans without service accounts, identities or Trusted IPs, the essentials are read-only service tokens with expiry, one per consumer, prefix-based scanning and a rotation drill. Larger organisations should make OIDC identities the default for CI and Kubernetes, alert on every personal token created and review service account roles and group membership every quarter.

Framework mapping

Common failure patterns

• A CLI token baked into an image. A developer's dp.ct. token, with write access to every project that person can see, ends up in a Dockerfile or CI variable.
• Revoking without rotating. The token is dead, but the database password it read last week is still valid.
• One service token shared by many applications. Nobody revokes it because everything would break, so it never expires.
• Trusted IPs left at the default. Production configs accept requests from 0.0.0.0/0, so a leaked token works from anywhere.
• Wildcard OIDC claims. A subject such as any branch in any repository lets untrusted workflows assume a production identity.
• Fallback files left behind. Encrypted copies of secrets remain on decommissioned or shared hosts after the token is gone.

Practitioner checklist

• Keep the seven-prefix revocation table in the on-call runbook.
• Scan repositories, images and CI logs for every dp. prefix, not only personal tokens.
• Ban personal and CLI tokens outside developer machines.
• Give every service token an expiry, keep it read-only and use one per consumer.
• Use service account identities with exact-match aud and sub for CI and Kubernetes.
• Keep workplace Owners and Admins few; grant project roles per environment and review groups.
• Replace 0.0.0.0/0 in Trusted IPs on production configs with stable egress ranges.
• Stream activity logs and alert on token, service account, identity, role and integration events.
• After any revocation, rotate every secret the token could read, guided by access logs.
• Run doppler run clean --all when decommissioning hosts or after a leak.

Standards and references

• Doppler: Auth Token Formats
• Doppler: Service Tokens
• Doppler: Service Account Identities
• Doppler: Project Permissions
• Doppler: Trusted IPs
• Doppler: Secret Access Logs
• Doppler: Activity Log Event Schema
• NIST: SP 800-53 Rev. 5 Security and Privacy Controls

Related NHI Mgmt Group resources: Secrets Management Guide · Akeyless, Doppler and 1Password Machine Access Guide · Akeyless Security Guide · 1Password Security Guide · Secrets Zero Problem Guide