Create a role binding

POST/admin/role-bindingsCreate a role binding

Grant a role to a principal at an organization or project scope.

Parameters

X-Pinecone-Api-Versionstringheaderrequired

Required date-based version header

default "2026-07"

Request body

required

Principal, resource scope, and role to bind.

application/json

objectCreateRoleBindingRequest

principal_idstringrequired

Principal ID. Format depends on `principal_type`.

principal_typestringrequired

The kind of principal that receives permissions from a role binding. Possible values: `user`, `service_account`, `api_key`, `invite`.

resource_idstring

Project UUID. Required when `resource_type` is `project`; omit for `organization` scope.

resource_typestringrequired

The kind of resource scope a role binding applies to. Possible values: `organization`, `project`.

rolestringrequired

A role assigned to a principal at a resource scope.

Example request

{
  "principal_id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "principal_type": "service_account",
  "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
  "resource_type": "project",
  "role": "DataPlaneEditor"
}

Responses

objectRoleBinding

Grants a `role` to a `principal` at a `resource` scope.

created_atstring · date-timerequired

When the role binding was created.

idstring · uuidrequired

The unique ID of the role binding.

principal_idstringrequired

The principal's ID. A UUID for all principal types (`user`, `service_account`, `api_key`, `invite`).

principal_typestringrequired

The kind of principal that receives permissions from a role binding. Possible values: `user`, `service_account`, `api_key`, `invite`.

resource_idstringrequired

The organization or project that the binding is scoped to.

resource_typestringrequired

The kind of resource scope a role binding applies to. Possible values: `organization`, `project`.

rolestringrequired

A role assigned to a principal at a resource scope.

Example response

{
  "created_at": "2026-04-10T15:23:00Z",
  "id": "9a8e3528-b9c0-4358-84ce-84c28e91b566",
  "principal_id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "principal_type": "service_account",
  "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
  "resource_type": "project",
  "role": "DataPlaneEditor"
}

objectErrorResponse

The response shape used for all error responses.

errorobjectrequired

Detailed information about the error that occurred.

Show child attributes

codestringrequired

The error code. Possible values: `OK`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `QUOTA_EXCEEDED`, `NOT_FOUND`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `UNAUTHENTICATED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `FORBIDDEN`, or `UNPROCESSABLE_ENTITY`.

detailsobject

Additional information about the error. This field is not guaranteed to be present.

messagestringrequired

statusintegerrequired

The HTTP status code of the error.

Example response

{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "Bad request. The request body included invalid request parameters."
  },
  "status": 400
}

objectErrorResponse

The response shape used for all error responses.

errorobjectrequired

Detailed information about the error that occurred.

Show child attributes

codestringrequired

detailsobject

Additional information about the error. This field is not guaranteed to be present.

messagestringrequired

statusintegerrequired

The HTTP status code of the error.

Example response

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Invalid API key."
  },
  "status": 401
}

objectErrorResponse

The response shape used for all error responses.

errorobjectrequired

Detailed information about the error that occurred.

Show child attributes

codestringrequired

detailsobject

Additional information about the error. This field is not guaranteed to be present.

messagestringrequired

statusintegerrequired

The HTTP status code of the error.

Example response

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "The index exceeds the project quota of 5 pods by 2 pods. Upgrade your account or change the project settings to increase the quota."
  },
  "status": 429
}

objectErrorResponse

The response shape used for all error responses.

errorobjectrequired

Detailed information about the error that occurred.

Show child attributes

codestringrequired

detailsobject

Additional information about the error. This field is not guaranteed to be present.

messagestringrequired

statusintegerrequired

The HTTP status code of the error.

Example response

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "The index exceeds the project quota of 5 pods by 2 pods. Upgrade your account or change the project settings to increase the quota."
  },
  "status": 429
}

objectErrorResponse

The response shape used for all error responses.

errorobjectrequired

Detailed information about the error that occurred.

Show child attributes

codestringrequired

detailsobject

Additional information about the error. This field is not guaranteed to be present.

messagestringrequired

statusintegerrequired

The HTTP status code of the error.

Example response

{
  "error": {
    "code": "ALREADY_EXISTS",
    "message": "This email already belongs to a member of the organization."
  },
  "status": 409
}

objectErrorResponse

The response shape used for all error responses.

errorobjectrequired

Detailed information about the error that occurred.

Show child attributes

codestringrequired

detailsobject

Additional information about the error. This field is not guaranteed to be present.

messagestringrequired

statusintegerrequired

The HTTP status code of the error.

Example response

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "The index exceeds the project quota of 5 pods by 2 pods. Upgrade your account or change the project settings to increase the quota."
  },
  "status": 429
}

objectErrorResponse

The response shape used for all error responses.

errorobjectrequired

Detailed information about the error that occurred.

Show child attributes

codestringrequired

detailsobject

Additional information about the error. This field is not guaranteed to be present.

messagestringrequired

statusintegerrequired

The HTTP status code of the error.

Example response

{
  "error": {
    "code": "UNKNOWN",
    "message": "Internal server error"
  },
  "status": 500
}

Examples

X-Pinecone-Api-Versionrequiredheader parameter

curl -X POST 'https://api.pinecone.io/admin/role-bindings' \
  -H 'Content-Type: application/json' \
  -d '{"principal_id":"e2e92523-85dc-4142-b8c2-e681be8b78df","principal_type":"service_account","resource_id":"a2f7dddb-1597-4eff-9f71-535fde243f58","resource_type":"project","role":"ProjectOwner"}'

const response = await fetch('https://api.pinecone.io/admin/role-bindings', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"principal_id":"e2e92523-85dc-4142-b8c2-e681be8b78df","principal_type":"service_account","resource_id":"a2f7dddb-1597-4eff-9f71-535fde243f58","resource_type":"project","role":"ProjectOwner"}),
});
const data = await response.json();

const response = await fetch('https://api.pinecone.io/admin/role-bindings', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: "{\"principal_id\":\"e2e92523-85dc-4142-b8c2-e681be8b78df\",\"principal_type\":\"service_account\",\"resource_id\":\"a2f7dddb-1597-4eff-9f71-535fde243f58\",\"resource_type\":\"project\",\"role\":\"ProjectOwner\"}" });
console.log(await response.json());

import requests

response = requests.request(
    "POST",
    "https://api.pinecone.io/admin/role-bindings",
    headers={"Content-Type": "application/json"},
    data='{"principal_id":"e2e92523-85dc-4142-b8c2-e681be8b78df","principal_type":"service_account","resource_id":"a2f7dddb-1597-4eff-9f71-535fde243f58","resource_type":"project","role":"ProjectOwner"}',
)
print(response.json())

package main

import (
	"context"
	"net/http"
	"strings"
)

func main() {
	ctx := context.Background()
	body := strings.NewReader(`{"principal_id":"e2e92523-85dc-4142-b8c2-e681be8b78df","principal_type":"service_account","resource_id":"a2f7dddb-1597-4eff-9f71-535fde243f58","resource_type":"project","role":"ProjectOwner"}`)
	req, err := http.NewRequestWithContext(ctx, "POST", "https://api.pinecone.io/admin/role-bindings", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
}

<?php
$request = curl_init("https://api.pinecone.io/admin/role-bindings");
curl_setopt($request, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($request, CURLOPT_POSTFIELDS, "{\"principal_id\":\"e2e92523-85dc-4142-b8c2-e681be8b78df\",\"principal_type\":\"service_account\",\"resource_id\":\"a2f7dddb-1597-4eff-9f71-535fde243f58\",\"resource_type\":\"project\",\"role\":\"ProjectOwner\"}");
curl_setopt($request, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($request);
curl_close($request);

var request = HttpRequest.newBuilder(URI.create("https://api.pinecone.io/admin/role-bindings"))
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"principal_id\":\"e2e92523-85dc-4142-b8c2-e681be8b78df\",\"principal_type\":\"service_account\",\"resource_id\":\"a2f7dddb-1597-4eff-9f71-535fde243f58\",\"resource_type\":\"project\",\"role\":\"ProjectOwner\"}"))
    .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

require 'net/http'

uri = URI("https://api.pinecone.io/admin/role-bindings")
request = Net::HTTPGenericRequest.new("POST", true, true, uri)
request['Content-Type'] = 'application/json'
request.body = "{\"principal_id\":\"e2e92523-85dc-4142-b8c2-e681be8b78df\",\"principal_type\":\"service_account\",\"resource_id\":\"a2f7dddb-1597-4eff-9f71-535fde243f58\",\"resource_type\":\"project\",\"role\":\"ProjectOwner\"}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.pinecone.io/admin/role-bindings");
request.Content = new StringContent("{\"principal_id\":\"e2e92523-85dc-4142-b8c2-e681be8b78df\",\"principal_type\":\"service_account\",\"resource_id\":\"a2f7dddb-1597-4eff-9f71-535fde243f58\",\"resource_type\":\"project\",\"role\":\"ProjectOwner\"}", Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);

{
  "created_at": "2026-04-10T15:23:00Z",
  "id": "9a8e3528-b9c0-4358-84ce-84c28e91b566",
  "principal_id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "principal_type": "service_account",
  "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
  "resource_type": "project",
  "role": "DataPlaneEditor"
}

{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "Bad request. The request body included invalid request parameters."
  },
  "status": 400
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Invalid API key."
  },
  "status": 401
}

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "The index exceeds the project quota of 5 pods by 2 pods. Upgrade your account or change the project settings to increase the quota."
  },
  "status": 429
}

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "The index exceeds the project quota of 5 pods by 2 pods. Upgrade your account or change the project settings to increase the quota."
  },
  "status": 429
}

{
  "error": {
    "code": "ALREADY_EXISTS",
    "message": "This email already belongs to a member of the organization."
  },
  "status": 409
}

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "The index exceeds the project quota of 5 pods by 2 pods. Upgrade your account or change the project settings to increase the quota."
  },
  "status": 429
}

{
  "error": {
    "code": "UNKNOWN",
    "message": "Internal server error"
  },
  "status": 500
}

Search documentation

API Keys

Organizations

Projects

Users

Invites

Service Accounts

Role Bindings

Parameters

Request body

Responses

API Keys

Organizations

Projects

Users

Invites

Service Accounts

Role Bindings