Manage roles and access

Assign and manage roles for users, service accounts, and API keys using the Pinecone console or the Admin API.

Pinecone uses role-based access controls (RBAC) to manage access to resources. Users, service accounts, and API keys are all principals, and a principal's access is determined by the roles assigned to it for a resource (an organization or a project).

This page shows how to assign and manage roles in the Pinecone console and programmatically with the Admin API.

Common role assignments

A user must have an organization role to belong to the organization, and gains access to a project through one or more project roles. A principal's effective permissions are the union of all the roles it holds, so you can combine roles to grant exactly the access a user needs.

The following table maps common scenarios to the roles to assign:

Scenario	Organization role	Project role(s)
Administer the organization and every project	`OrgOwner`	None (inherits owner access to all projects)
Create and manage projects, but not billing or members	`OrgManager`	Assign per project as needed
Manage billing, subscriptions, and usage	`OrgBillingAdmin`	None
Lead a single project, including its members and API keys	`OrgMember`	`ProjectOwner`
Build and query in a project, without managing members or API keys	`OrgMember`	`ProjectManager`
Read and write index data only	`OrgMember`	`ProjectMember` and `DataPlaneEditor`
Read-only access to a project's resources and data	`OrgMember`	`ProjectMember`, `ControlPlaneViewer`, and `DataPlaneViewer`
Work across two projects at different access levels	`OrgMember`	`ProjectManager` on one project and `ProjectMember` with `DataPlaneViewer` on another

Invite a developer to a project

Invite a user as an organization member and grant them the ProjectManager role so they can build and query in a single project without managing its members or API keys.

In the console, add the user from Manage project members and select the Project manager role. With the Admin API, include both roles in the role_bindings array when you invite the user:

curl

PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/invites" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  -d '{
    "email": "developer@example.com",
    "role_bindings": [
      {
        "resource_type": "organization",
        "role": "OrgMember"
      },
      {
        "resource_type": "project",
        "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
        "role": "ProjectManager"
      }
    ]
  }'

For more information, see Assign roles when creating a principal.

Grant an existing user read-only data access

To give a user who is already in your organization read-only access to a project's data, assign the ProjectMember role for baseline project access and the DataPlaneViewer role for read-only data. Each role binding is a separate request.

First, add the user to the project with the ProjectMember role:

curl

PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/role-bindings" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  -d '{
    "principal_type": "user",
    "principal_id": "c7b1f0a2-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
    "resource_type": "project",
    "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
    "role": "ProjectMember"
  }'

Then, grant read-only data access with the DataPlaneViewer role:

curl

PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/role-bindings" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  -d '{
    "principal_type": "user",
    "principal_id": "c7b1f0a2-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
    "resource_type": "project",
    "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
    "role": "DataPlaneViewer"
  }'

Extend a user's access with an additional role

Because effective permissions are the union of all roles, you can broaden access by adding another role rather than replacing the existing one. The user from the previous example holds ProjectMember and DataPlaneViewer; add ControlPlaneViewer to also allow read-only access to the project's indexes, assistants, backups, and collections:

curl

PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/role-bindings" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  -d '{
    "principal_type": "user",
    "principal_id": "c7b1f0a2-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
    "resource_type": "project",
    "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
    "role": "ControlPlaneViewer"
  }'

The user now holds ProjectMember, DataPlaneViewer, and ControlPlaneViewer on the project, giving read-only access to all of its resources and data. For more information, see Create a role binding.

Manage roles in the console

You can assign and change roles when you manage principals in the console:

Manage roles with the Admin API

The Admin API represents each role assignment as a role binding that grants one role to one principal for one resource scope. You can assign roles when you create a principal, or manage role bindings directly after creation.

Assign roles when creating a principal

When you invite a user or create a service account, grant roles with the role_bindings field. Set resource_type to organization or project; for project scope, include the project's resource_id.

Invite a user as an organization member with a project role:

curl

PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/invites" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  -d '{
    "email": "newhire@example.com",
    "role_bindings": [
      {
        "resource_type": "organization",
        "role": "OrgMember"
      },
      {
        "resource_type": "project",
        "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
        "role": "ProjectMember"
      }
    ]
  }'

Create a service account with an access role:

curl

PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/service-accounts" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  -d '{
    "name": "ci-prod",
    "role_bindings": [
      {
        "resource_type": "project",
        "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
        "role": "DataPlaneEditor"
      }
    ]
  }'

For API keys, assign project roles with the roles field instead. For more information, see Manage API keys.

Create a role binding

To grant a role to an existing principal, create a role binding:

curl

PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/role-bindings" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
  -d '{
    "principal_type": "service_account",
    "principal_id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "resource_type": "project",
    "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
    "role": "DataPlaneEditor"
  }'

For more information, see Create a role binding.

List role bindings

Role bindings aren't included in the responses for users, invites, or service accounts. To list the roles assigned to a principal, filter by principal_type and principal_id:

curl

PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl "https://api.pinecone.io/admin/role-bindings?principal_type=service_account&principal_id=f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"

For more information, see List role bindings and Fetch a role binding.

Delete a role binding

To revoke a role, delete its role binding:

curl

PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl -X DELETE "https://api.pinecone.io/admin/role-bindings/9a8e3528-b9c0-4358-84ce-84c28e91b566" \
  -H "Accept: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN"

For more information, see Delete a role binding.