User permissions

In Neon, access works in two layers. Your organization role sets a baseline level of access across every project in the org, and per-project permissions grant additional access on individual projects. This page explains how the two layers combine and what each role and permission lets you do.

This page is mainly for organization Admins, who decide who can see and change projects.

For an overview of organizations, see the Organizations page.

How permissions work

Your organization role and any per-project permissions combine, and they're additive: your effective access on a project is the higher of the two. A per-project permission can only raise your access, never lower it. (Restricting access on a single project isn't supported yet. See Notes and limitations.)

Access is closed by default for Collaborators. Without an explicit per-project grant, a project doesn't appear in a Collaborator's list at all, and Neon responds as though it doesn't exist.

Common setups

These examples show how an organization role and per-project grants combine:

A couple of behaviors are worth calling out:

• Viewers can still create their own projects. The read-only limit applies to projects a Viewer didn't create. Any organization member except a Collaborator can create a project, and whoever creates a project becomes Admin on it. They keep that access if their organization role changes later, so to reduce it, grant them a lower permission on the project explicitly.
• Deleting a project takes Admin access on that project, not the Admin organization role. Anyone granted Admin on a project, along with any organization Admin, can delete it after typing the project name to confirm.

Assign project access

Access comes down to two things: a person's organization role sets their baseline everywhere, and per-project permissions add to it where they need more.

1. Set the organization role

   Start with the organization role, which sets a person's baseline access across every project. On the organization's People page, select Invite member to add someone with a role, or open the more options menu (⋮) next to an existing member and choose Edit member to change it. Match the role to how much of the organization they should see; for what each role grants, see Organization roles.

2. Grant per-project permissions

   To give someone more than their baseline on a specific project, open that project's Settings → Project permissions, select Grant permission, choose a level (Viewer, Editor, or Admin), and pick one or more members. A grant only ever raises access: a person's effective permission is the higher of their organization role and the grant. For what each level allows, see Per-project permissions.

   

3. Review who has access

   The same Project permissions page lists everyone who can reach the project, with an Inherited or explicit tag on each. Change or revoke an explicit grant from the more options menu (⋮) next to a person's name.

Organization roles

Every member of an organization has one of four roles. Each role sets a baseline level of access on every project in the organization:

The following table shows what each role can do at the organization level:

Personal API keys are available to any member and are scoped to that member's own access. Only Admins can create organization or project-scoped API keys. See Manage API keys.

Per-project permissions

A per-project permission grants access on a single project, on top of a person's organization role. There are three levels, the same Viewer, Editor, and Admin levels an organization role grants by default:

• Viewer: Read-only project access.
• Editor: Connect, query, and edit project resources.
• Admin: Manage access, settings, and the project lifecycle.

To grant one, see Assign project access. The following table shows what each level allows:

As a rule, Viewers can see a project's resources, Editors can change them, and Admins manage access and the project itself.

Newer Neon products, including Managed Better Auth, Storage, Functions, and the AI Gateway, don't fully enforce per-project permissions yet. Per-project permission support for these products is being added over time.

Inherited and explicit access

On a project's Project permissions page, access shows up in one of two ways:

• Inherited: Access comes from the user's organization role, not from a grant on this project. Organization Admins always appear as Admin with an Inherited tag, because they can manage every project.
• Explicit: The user was granted a permission directly on this project.

When a user has both an organization-role default and an explicit grant, the higher of the two applies.

Manage project access with the API

You can manage project access programmatically with the Neon API. These calls require an organization API key with the Admin role. Roles are sent in the request as lowercase values (viewer, editor, admin) and returned in responses as uppercase permission levels (VIEWER, EDITOR, ADMIN). Response fields vary by endpoint; get a member's member_id from the List project members response.

The Neon CLI doesn't have a dedicated command for these operations yet. You can call the same routes with the neon api passthrough command, for example neon api /projects/{project_id}/members/{member_id}/role -X PUT -F role=editor.

List project members

Lists the organization members who have access to a project, with each member's organization role, their explicit project role (if any), and their effective permission.

curl --request GET \
     --url 'https://console.neon.tech/api/v2/projects/{project_id}/members' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $ORG_API_KEY' | jq

Example response:

{
  "project_members": [
    {
      "member_id": "abc123de-4567-8fab-9012-3cdef4567890",
      "user_id": "def456gh-7890-1abc-2def-3ghi4567890j",
      "email": "alex@example.com",
      "org_role": "admin",
      "project_role": "admin",
      "org_default_project_permission": "ADMIN",
      "effective_project_permission": "ADMIN",
      "grant_source": "org_role_default"
    }
  ]
}

Set a member's project role

Grants or updates an organization member's role on a project. Send viewer, editor, or admin in the request body.

curl --request PUT \
     --url 'https://console.neon.tech/api/v2/projects/{project_id}/members/{member_id}/role' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $ORG_API_KEY' \
     --header 'content-type: application/json' \
     --data '{"role": "editor"}' | jq

Example response:

{
  "project_id": "example-project-12345678",
  "member_id": "abc123de-4567-8fab-9012-3cdef4567890",
  "user_id": "def456gh-7890-1abc-2def-3ghi4567890j",
  "email": "sam@example.com",
  "org_role": "collaborator",
  "project_role": "editor",
  "explicit_project_permission": "EDITOR",
  "effective_project_permission": "EDITOR"
}

Remove a member's project role

Removes a member's explicit role on a project. Their organization role's default access still applies. On success, returns the member's updated access.

curl --request DELETE \
     --url 'https://console.neon.tech/api/v2/projects/{project_id}/members/{member_id}/role' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $ORG_API_KEY'

Legacy permissions

The model on this page is rolling out to organizations gradually. Until it reaches your organization, you'll see the legacy model: three roles (Admin, Member, and Collaborator), where Members share one access level across every project and access is granted per project through project sharing.

When the new model reaches your organization, everyone keeps the access they have today. No action is required. The legacy roles map as follows:

The new Collaborator organization role is not the same as the legacy project-sharing collaborator, even though they share a name:

Project sharing is being deprecated and will be removed in a future release. For new access, use the Collaborator role plus per-project permissions instead.

Notes and limitations

• Access can only be added, not restricted: Per-project permissions raise a user's access above their organization-role baseline; they can't reduce it. There's currently no way to block an Editor from a single project; they keep their baseline access on all projects in the organization.
• Feedback: The permissions system may not meet every need for granular control. Share your feedback via the Feedback form or our Discord feedback channel.
• Email notifications: For organization-owned projects, Neon sends approaching maximum storage notification emails to organization Admins only, not to other members. Admins are responsible for billing and plan limits at the organization level, which aligns with who can manage organization billing.