neonctl: org-scoped API key vs user-scoped API key
Explains neonctl permission failures from using the wrong API key scope. Use when commands fail with authorization errors even though the key is valid, especially across multiple projects or an org. Picks a user-scoped key for broad access or an org-scoped key for least privilege, and matches the key to the job. Not for invalid-key 401s.
neonctl: org-scoped API key vs user-scoped API key
TL;DR: Neon issues API keys at different scopes: user-scoped keys act with your full account access, while org-scoped keys are limited to that organization. An org-scoped key used against a personal project (or the wrong org) fails authorization even though the key is valid. Check which scope your key has in the console, then use a user-scoped key for cross-org work or generate an org-scoped key inside the right org for least-privilege automation.
neonctl authorization failures with a valid API key (wrong scope)Steps
- In the Neon console, check the key's scope: user-level or organization-level.
- If the command targets projects outside the key's org, switch to a user-scoped key (or a key scoped to the correct org).
- For CI limited to one org's projects, prefer an org-scoped key from that org: least privilege, and a leak is contained.
- Re-authenticate with the correctly scoped key and rerun. Expected: authorization succeeds.
When this applies
not authorized/ permission errors with a key that passes the 401 check- automation touching projects across multiple orgs
- choosing key scope for a new CI integration
When it doesn't
Authentication failed— the key is invalid, scope is irrelevant- project-not-found for a project that genuinely does not exist
- SSO/browser login issues
Compatibility
neonctl; Neon console API key scopes (user vs organization). Verified against the neon-pkgs agent notes.
Variant phrasings
- neonctl org scoped api key
- neon api key scopes user vs org
- neonctl not authorized valid key
Root cause
Authorization is checked against both key validity and key scope. A valid org-scoped key simply has no rights outside its org, so cross-org calls fail at the authorization layer with no hint that scope (not the key) is the problem.
Edge cases
- a user-scoped key is powerful; store it as carefully as a password
- leaving an org can silently break automations built on your user-scoped key; prefer org keys for shared CI
- key scope is set at creation; you cannot widen a key later, only create a new one
Maintainer review
No maintainer verification is recorded for this version.
This records the version a maintainer checked. It does not assert that the version is the latest upstream release.