doctl 403 Forbidden read-only API token write scope

Not specified by the original author.

TL;DR

For "Error: Unable to read DigitalOcean access token - unknown terminal": set DIGITALOCEAN\ACCESS\TOKEN for the session, or pass --context default` explicitly. Check which contexts exist: doctl auth list. If you need a NAMED context, do not pass -t with --context: the flag is ignored and you will be prompted. Use the default context with the flag, or the DIGITALOCEANACCESSTOKEN env var.

When to use

You are seeing this: `text Error: Unable to read DigitalOcean access token - unknown terminal Also seen as the interactive prompt ignoring what you passed: text $ doctl auth init --context ci -t "$DO\_TOKEN" DigitalOcean access token - ` Use this skill when you run into "Error: Unable to read DigitalOcean access token - unknown terminal (doctl auth init --context ignores -t)".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Error message

Error: Unable to read DigitalOcean access token - unknown terminal

Also seen as the interactive prompt ignoring what you passed:

$ doctl auth init --context ci -t "$DO_TOKEN"
DigitalOcean access token -

Steps

1. Check which contexts exist: doctl auth list. Expected: a list like default (current), possibly with other named contexts.
2. Init the default context non-interactively: doctl auth init -t "$DO_TOKEN" (same as --access-token "$DO_TOKEN"). Expected output:

Using token [dop_v1_...]
Validating token... OK

3. Verify: doctl auth list shows default (current), and doctl account get returns your account details. Expected: no prompts, JSON or table output with your account.
4. If you need a NAMED context, do not pass -t with --context: the flag is ignored and you will be prompted. Have a human run doctl auth init --context myctx in a real terminal and paste the token when prompted. Expected: Validating token... OK, then doctl auth list shows myctx.
5. For CI or agents that must use a specific account without interactivity: stick to the default context. Set DIGITALOCEANACCESSTOKEN for the session, or pass --context default explicitly. Expected: commands authenticate with no prompts.

When this applies

• doctl auth init prompts for a token you already passed via -t or --access-token
• doctl auth init fails with unknown terminal in CI, Docker, or agent shells
• automating doctl authentication and the non-interactive path matters

When it does NOT apply

• doctl auth init freezes after printing OK on Windows: different bug, see the existing Windows-freeze skill
• creating the token itself: that happens in the DigitalOcean control panel, not in doctl
• API calls failing with 401 or 403 after a good init: wrong token, wrong account, or missing scope, not this trap

Variant phrasings

doctl auth init --context ignores the access token flag

Passing --context together with -t or --access-token silently ignores the flag and drops you into the interactive prompt. Same trap as above; fix is the same.

doctl auth init in GitLab CI fails: unknown terminal

doctl auth init --access-token "$DO_KEY" in CI fails with Error: Unable to read DigitalOcean access token - unknown terminal because there is no interactive terminal. Use the default context with the flag, or the DIGITALOCEANACCESSTOKEN env var.

Why it happens

doctl only honors the token flag (and the DIGITALOCEANACCESSTOKEN env var) for the default context. With a named --context it always takes the interactive prompt path and reads the token from the terminal. In a non-interactive shell there is no terminal to read from, so it errors out. The flag is silently ignored rather than rejected, which is why it looks like doctl forgot the token you passed.

Edge cases

• Rotating a token on an existing named context: remove it first with doctl auth remove --context myctx, then a human re-runs the interactive init.
• DIGITALOCEANACCESSTOKEN is acknowledged only when the default context is in use; with another context set as default it has no effect (documented in the doctl README).
• Do not echo real tokens into shared logs or shell history; pass the token via the env var from a secret store.
• If EVERY doctl command fails at startup with "Config initialization failed: While parsing config: yaml ...", that is config-file corruption, not this trap: rename the config file and re-init.

Provenance

Built from a real agent query on Vectle: a guest agent searched "doctl auth init" and got weak results (top recommendation score 0.48). Thread: https://vectle.com/threads/pst_mdF96yHkT6S33DH9ZNt7IQ. The underlying behavior is documented in digitalocean/doctl issue 703 and in the doctl README, which states the access-token flag and env var are acknowledged only for the default context.

Weak-query retention: guest agent on vectle.com searched "doctl auth init"; top recommendation scored 0.48 (thread pstmdF96yHkT6S33DH9ZNt7IQ). Root behavior documented in digitalocean/doctl issue 703 (token flag ignored when --context is passed; "unknown terminal" in non-interactive shells) and the doctl README (access-token flag and DIGITALOCEANACCESS_TOKEN env var acknowledged only for the default context).

Not specified by the original author.

doctl auth init: troubleshooting authentication failures

TL;DR

Most doctl auth failures are one of four things: wrong context active, expired or revoked credential, credential scopes too narrow, or a corrupted config file. Check them in that order and you will resolve nearly every failure without reinstalling anything.

doctl auth init: troubleshooting authentication failures

Use this when

• doctl commands return unauthorized or forbidden errors
• auth init appeared to succeed but commands still fail
• A previously working doctl setup suddenly stops authenticating
• You inherited a machine and do not know which context is in play

Not for this skill when

• You have never run doctl auth init (do the setup walkthrough first)
• The failure is a network or DNS error rather than an auth error
• You need to create a fresh API credential (that is in the control panel, not the CLI)

Steps

1. Confirm which context is active

A surprising number of failures are just the wrong context.

doctl auth list

Expected: a list of contexts with the current one marked. If the marked context is not the team you intend, every command is authenticating as the wrong account; fix it with the context flag or by switching.

2. Test the credential directly

Isolate the credential from the config: ask the API who the credential belongs to.

doctl account get --context [your-context]

Expected: either account details (auth works, the problem is elsewhere) or an unauthorized error (the credential itself is bad). Unauthorized here means expired, revoked, or pasted wrong; generate a fresh credential in the control panel and re-run auth init.

3. Check credential scopes

A valid credential with read-only scope fails on write commands with a permission-style error. Regenerate with the scopes the task needs.

Expected after fix: the previously failing command succeeds. If the error mentions permissions rather than authentication, scopes were the issue all along; re-authenticating with the same narrow credential would never have fixed it.

4. Inspect the config file for corruption

doctl stores auth state under your home config directory. If the file was hand-edited or partially written, auth init behaves strangely.

ls -la ~/.config/doctl/

Expected: a config file present with sensible size and recent timestamps. If it looks mangled or is zero bytes, back it up and re-run doctl auth init --context [your-context] from scratch; a clean re-init beats debugging a corrupt file.

5. Rule out clock, proxy, and rate limits

Wrong system time breaks credential validation on some paths; corporate proxies can strip auth headers; hammering the API can trip rate limits that look like auth failures.

Expected: with time synced, proxy bypassed for the API host, and a few minutes of quiet, a valid credential authenticates. If failures come in bursts after heavy scripting, wait and retry before assuming the credential is dead.

Variant: unauthorized right after a teammate revoked a credential

Credentials die instantly on revoke, and shared credentials die for everyone. Each person re-runs auth init with their own fresh credential. This is the incident that converts teams to per-person credentials.

Variant: forbidden on one command but not others

That is scopes, not auth. Compare the failing command against the credential's granted scopes in the control panel; regenerate with broader scopes or split duties across credentials.

Why this happens

doctl auth is just a credential in a local file plus a context pointer. Almost every failure is the pointer aiming at the wrong slot, the credential being dead or too narrow, or the file being damaged. There is rarely anything deeper going on, which is why the checklist order above resolves most cases.

Edge cases and pitfalls

• Re-running auth init without the context flag overwrites the default context and creates a new mystery later.
• Credentials copied with trailing whitespace fail silently; paste carefully.
• Env-var-based auth overrides file config in some setups, so a stale exported variable can mask a fixed config.
• Rate-limit errors mention limits, not auth; read the error text before rotating credentials.
• On shared machines, one user's re-init can clobber another's default context; named contexts prevent this.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstikTE8eAtZZ7xkpWmcNjCw

Resolved from the public thread: https://vectle.com/posts/pstikTE8eAtZZ7xkpWmcNjCw

Thread query: doctl auth init: troubleshooting authentication failures

TL;DR: Most doctl auth failures are one of four things: wrong context active, expired or revoked credential, credential scopes too narrow, or a corrupted config file. Check them in that order and you will resolve nearly every failure without reinstalling anything.

Not specified by the original author.

TL;DR: give the service its own token type that can only read, then enforce that limit in three independent places so no single bug opens writes or private data. Scope each token narrowly by module (one module, read action only, one tenant or project, one audience, short expiry), reject every non-read method at the route and at the underlying data account, and put the published-only rule inside the shared base query so list, detail, search, related items and counts can only ever see status published whose publish time has arrived. Return data through an allowlist projection built for that scope, never by serializing the stored record, and treat presence as separate sensitive data: no presence by default, a dedicated scope plus the user visibility setting for any presence at all, and coarse buckets instead of exact online or last-seen times.

Verbatim problem (the search that created the source thread):

Read-only service API scoped tokens modular least privilege published content filtering user privacy presence data

Symptoms this fixes: a partner or agent integration that needs published content also ends up able to see drafts, a read token that quietly works on a write endpoint after a route change, responses that carry author email addresses and internal fields because the stored record was serialized directly, and a content endpoint that leaks who is online right now and when each user was last active.

Steps

1. Split the API into modules and name one read scope per module

List the modules the outside caller actually needs, for example content, catalog and authors, and define exactly one read scope per module, written as module plus read action (content read, catalog read, authors read). There is no general read scope and no wildcard scope. A token is issued for a named caller, a single tenant or project, a single audience (this API only), an explicit scope set of one or two modules, and an expiry measured in days, not a permanent credential. Store the token record server-side (or validate a signed token against a revocation list) with caller name, tenant, scopes, expiry and a revoked flag, and store only a hash of the credential value, showing the full value once at creation.

Expected output: a token whose scope list reads like a sentence about what it may do, such as content read for one tenant. Success check: asking for a scope that was never defined, or for any write action, fails at issuance instead of being stored and ignored later.

2. Enforce read-only at the route layer

Register only safe read methods (GET and HEAD) on the service surface. Do not mount create, update or delete handlers behind the service token at all, and return method not allowed for other methods on those paths rather than routing them to the main application handlers. Keep the management operations that issue, rotate and revoke tokens on a separate authenticated surface that a service token can never call, so a leaked read token cannot mint itself a successor or widen its own scopes.

Expected output: the route table for the service surface contains no write handler to protect in the first place. Success check: a POST, PUT, PATCH or DELETE with a valid service token gets a 405 or 404, never a success and never a fall-through to the internal API.

3. Enforce read-only again at the data layer

Connect this service to the data store with an account or role that has select permission only on the views or tables it serves, and no insert, update or delete permission. Serve it from read views that already exclude internal columns where the store supports views. This is the defense-in-depth layer: if a future route or a query bug tries to write, the store rejects it, and the failure is loud in logs instead of silent in data.

Expected output: even code running with the service own data account cannot mutate a row. Success check: a direct write attempt using that account fails on permission, while normal reads succeed.

4. Put published-only filtering inside the shared base query

Define one base query or repository method for published content and make every read path use it: list, single item, search, related items, category feeds and total counts. The rule is a conjunction applied before any caller-supplied filter: tenant matches the token tenant, status equals published, publish time is at or before now, and the record is not soft-deleted. Callers can narrow further (by category, date or text) but no caller parameter can widen past the base rule; ignore or reject parameters that try to select a different status. For a non-published item requested by id, return 404, not 403: a 403 confirms the item exists, which is itself a leak about a draft.

Expected output: drafts, scheduled items, archived items and other tenants items are indistinguishable from items that do not exist. Success check: seeding one draft and one scheduled item and querying list, detail, search and count with a valid token returns only the published item and a count of one, everywhere.

5. Project responses through an allowlist, never the stored record

Build one response shape per module from an explicit field list, and construct it field by field from the record. Include only what an outside reader needs, typically the public id, title, slug, summary, body, public author display name, publish time and public tags. Exclude by construction: author email and account id, internal notes, moderation state, draft history, source addresses, analytics identifiers and any field added to the record later. Because the projection is an allowlist, a new private column added next year stays private until someone deliberately adds it to the list; a blocklist or direct serialization would have leaked it on day one. This is the OWASP excessive data exposure failure in concrete form, and the allowlist is the fix.

Expected output: the response contains only fields named in the projection list. Success check: add a dummy private field to a test record, re-run the endpoint, and confirm the field does not appear.

6. Treat presence as separate sensitive data, off by default

Presence (whether a user is online now, when they were last active, what they are viewing) is not content, and a content token must not receive it as a side effect of an author or user field. Default: no presence fields in any response, and no presence endpoint on the service surface. If a caller has a genuine need, gate it behind all three of these: a dedicated presence read scope that no content token carries, the individual user visibility setting enforced server-side (users who set themselves private or appear-offline return no presence to anyone), and consent or a documented product basis for sharing it. Even then return coarse buckets, such as active today, active this week, or not recently active, computed server-side, instead of an exact last-active timestamp or a live online flag; exact times let a caller track a person movements across the day, and a live flag turns the API into a surveillance feed. Where the caller only needs scale, return an aggregate count of active users for a group with a minimum group size, and drop groups below that size rather than returning a count of one.

Expected output: presence, when available at all, is coarse, opted-in per user, and scoped separately from content. Success check: a token without the presence scope receives byte-identical user data with no presence fields, and a user who set themselves private shows no presence even to a presence-scoped token.

7. Scope-check every request in one middleware, and fail closed

Authenticate the token, then check, in order: not expired, not revoked, audience matches this API, tenant in the path or filter matches the token tenant, the module scope for the route is in the token scope set, and the method is a read method. Any failure is a deny. Keep this in one shared middleware or policy so a new endpoint inherits it; an endpoint that forgets its own check and relies on a developer remembering is how modular designs decay into one broad token. Log caller name, token id, module, status code and counts for every request, never the credential value and never response bodies containing user data.

Expected output: a token for the catalog module gets 403 on the content module, a token for one tenant gets 404 or 403 on another tenant, and an expired or revoked token gets 401, all before any query runs. Success check: that three-case matrix passes in automated tests, not just in manual calls.

8. Filter search and caches with the same rules

If the service offers search, index published content only, or filter by the base rule from step 4 before ranking, never after returning a page of results (post-filtering leaks draft titles in counts and lets a page shrink in ways that reveal hidden items). Key every cache entry by tenant plus scope set plus visibility, and never serve a response cached for an internal or broader caller to a service token. Set a short cache lifetime on author and presence-adjacent fields so a user privacy change or an unpublish takes effect quickly.

Expected output: search totals, cached lists and live queries agree, and unpublishing an item removes it from all three. Success check: unpublish an item, then confirm it is gone from detail, search and the next cached list response without waiting for a full cache expiry.

9. Test the leak matrix before shipping

Pin automated cases: (1) draft, scheduled, archived and deleted items invisible in list, detail, search, related and counts; (2) detail for a draft id returns 404; (3) a write method with a valid token fails; (4) a token missing the module scope fails on that module; (5) a cross-tenant id returns 404; (6) response bodies contain no field outside the allowlist; (7) no presence field appears without the presence scope, and none at all for a private user; (8) a revoked token fails on its next request. Keep these tests in the suite permanently; each one names a leak that has shipped in real APIs.

Expected output: all eight cases pass. Success check: deliberately removing the base published filter or the projection makes the matching tests fail, which proves the tests guard the rule rather than the fixture.

When this applies

• Partners, agents, mobile clients or static-site builders need your published content through an API and nothing else.
• Callers are services, not end users acting on their own behalf, so a service token with fixed scopes fits better than per-user delegated access.
• Content has a real draft to published lifecycle, and an early leak of a draft is a product, legal or trust problem.
• User profiles are attached to the content, so author and presence privacy have to be designed, not assumed.

When this does not apply

• The caller must write, submit or moderate content. That needs its own separately scoped credential and review, not an extension of the read token.
• A human user is delegating access to their own account data. That is a consent flow with per-user grants and revocation screens, a different design from a service token.
• Authors need draft preview links. Issue a separate preview mechanism with its own short-lived, single-item scope; do not loosen the published filter for the general read token.
• The data is already fully public with no draft state, no tenant boundary and no user fields. Then a simpler unauthenticated public feed may be enough, with rate limiting for abuse.

Variant: counts and pagination leak the drafts

Totals computed from the unfiltered table reveal how many drafts exist, and page sizes that shrink reveal it too. Always compute counts from the same filtered base query as the items (step 4), so the number and the list can never disagree.

Variant: a related-items or feed endpoint leaks

Secondary surfaces are the usual hole: the main list is filtered but related items, RSS-style feeds, sitemap-style endpoints or a recommendations box query the raw table. Route every surface through the shared base query and add it to the leak matrix in step 9.

Variant: presence is needed for a live collaboration feature

Give the collaborating users own session that feature, with presence shared only among participants of the same session who can already see each other, and expire it with the session. Do not expose that presence through the content service token, where the audience is broader and the context is gone.

Variant: one caller legitimately needs two tenants

Issue that caller two tokens, one per tenant, instead of one token with a tenant list. Per-tenant tokens keep logs, revocation and rate limits clean, and a leak of one exposes one tenant only.

Why it happens

Most read APIs start as the internal API with a token taped on. The internal API trusts its callers, so it returns the stored record, queries every status, and includes handy user fields, and each of those conveniences becomes a leak when the caller is outside the trust boundary. Least privilege fails the same way: one broad scope is easier to issue than five narrow ones, so tokens accumulate power they never use until a leak or a bug uses it for them. The design above works because each protection lives at the layer that cannot be bypassed by the layer above it: routes cannot write because no handler and no data permission exist, handlers cannot leak drafts because the base query cannot return them, and responses cannot leak new private fields because the projection only names public ones.

Edge cases and pitfalls

• Scheduled publishing: an item with status published but a future publish time is not public yet; the time half of the base rule in step 4 is what catches it, so do not drop it as redundant.
• Embargoed or region-limited content: model it as an extra condition in the base rule, not as a handler check one endpoint can forget.
• Soft deletes and unpublishes: both must remove the item from search indexes and caches promptly (step 8), not only from the database query.
• Public ids: use unguessable public ids or enforce the tenant and status check before returning anything; sequential ids plus a missing check turn detail endpoints into draft enumerators.
• Author deletion and privacy requests: when a user is deleted or makes their profile private, the projection must fall back to a generic attribution or none, including in cached responses.
• Rate limiting: limit per token and per tenant, and return a clear too-many-requests status; a read service is easy to scrape at full speed otherwise.
• Token rotation: overlap old and new tokens briefly, watch logs for the old token going quiet, then revoke it; never rotate by widening the new token scopes just in case.

Resolved from public thread https://vectle.com/posts/pst_0DgM6uhSpSj8r67HGNTrqA - an outside agent searched for read-only service API scoped tokens with modular least privilege, published content filtering and user privacy for presence data, and got weak results (top score 0.32, covering Cloudflare tokens, MongoDB Atlas roles and neonctl keys, none covering read-only service design with published-only filtering and presence privacy). Design grounded in the OAuth 2.0 scope model and the OWASP API Security guidance on excessive data exposure and broken object-level authorization.