Create a service account

POST/admin/service-accountsCreate a service account

Create a service account with optional initial role bindings; the client secret is returned only once.

Parameters

X-Pinecone-Api-Versionstringheaderrequired

Required date-based version header

default "2026-07"

Request body

required

The service account to create. Repeating this request may create duplicate service accounts.

application/json

objectCreateServiceAccountRequest

namestringrequired

The human-readable name of the service account.

maxLength 80 · minLength 1

role_bindingsarray of object

Optional initial role bindings. Omitting the field or passing an empty array creates the service account with no role bindings; roles can be added later via the role binding endpoints. A service account may be granted any organization- or project-scoped role. Not returned in the response.

maxItems 100 · minItems 0

Show child attributes

maxItems 100 · minItems 0

Show array items

A role to grant to the principal being created. `resource_type` selects the binding scope and acts as the tag for the entry. For `organization` scope, omit `resource_id`; the binding applies to the principal's organization (inferred from the request context). For `project` scope, `resource_id` is required and must be the project UUID.

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

{
  "name": "ci-prod",
  "role_bindings": [
    {
      "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
      "resource_type": "project",
      "role": "DataPlaneEditor"
    }
  ]
}

Responses

objectServiceAccountWithSecret

A service account with a newly issued OAuth `client_secret`. The secret is returned only once and cannot be retrieved later.

client_secretstringrequired

The OAuth client secret. Returned exactly once. Treat this value as a credential — store it securely and never log it.

service_accountobjectrequired

A service account. The OAuth `client_secret` is not included.

Show child attributes

client_idstringrequired

The OAuth client ID used by the service account to obtain access tokens. Used only for OAuth token exchange.

created_atstring · date-timerequired

The date and time the service account was created.

idstring · uuidrequired

The unique identifier for the service account. Use this as the path parameter on `/admin/service-accounts/{service_account_id}` endpoints and as the `principal_id` when querying or creating role bindings.

namestringrequired

A short human-readable label, set by the caller at creation time.

maxLength 80 · minLength 1

updated_atstring · date-timerequired

The date and time of the service account's most recent metadata update.

Example response

{
  "client_secret": "",
  "service_account": {
    "client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn",
    "created_at": "2026-04-10T15:23:00Z",
    "id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "name": "My Service Account",
    "updated_at": "2026-04-10T15:23:00Z"
  }
}

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": "UNKNOWN",
    "message": "Internal server error"
  },
  "status": 500
}

Examples

X-Pinecone-Api-Versionrequiredheader parameter

curl -X POST 'https://api.pinecone.io/admin/service-accounts' \
  -H 'Content-Type: application/json' \
  -d '{"name":"ci-prod","role_bindings":[{"resource_id":"string","resource_type":"project","role":"ProjectOwner"}]}'

const response = await fetch('https://api.pinecone.io/admin/service-accounts', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"name":"ci-prod","role_bindings":[{"resource_id":"string","resource_type":"project","role":"ProjectOwner"}]}),
});
const data = await response.json();

const response = await fetch('https://api.pinecone.io/admin/service-accounts', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: "{\"name\":\"ci-prod\",\"role_bindings\":[{\"resource_id\":\"string\",\"resource_type\":\"project\",\"role\":\"ProjectOwner\"}]}" });
console.log(await response.json());

import requests

response = requests.request(
    "POST",
    "https://api.pinecone.io/admin/service-accounts",
    headers={"Content-Type": "application/json"},
    data='{"name":"ci-prod","role_bindings":[{"resource_id":"string","resource_type":"project","role":"ProjectOwner"}]}',
)
print(response.json())

package main

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

func main() {
	ctx := context.Background()
	body := strings.NewReader(`{"name":"ci-prod","role_bindings":[{"resource_id":"string","resource_type":"project","role":"ProjectOwner"}]}`)
	req, err := http.NewRequestWithContext(ctx, "POST", "https://api.pinecone.io/admin/service-accounts", 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/service-accounts");
curl_setopt($request, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($request, CURLOPT_POSTFIELDS, "{\"name\":\"ci-prod\",\"role_bindings\":[{\"resource_id\":\"string\",\"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/service-accounts"))
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"name\":\"ci-prod\",\"role_bindings\":[{\"resource_id\":\"string\",\"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/service-accounts")
request = Net::HTTPGenericRequest.new("POST", true, true, uri)
request['Content-Type'] = 'application/json'
request.body = "{\"name\":\"ci-prod\",\"role_bindings\":[{\"resource_id\":\"string\",\"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/service-accounts");
request.Content = new StringContent("{\"name\":\"ci-prod\",\"role_bindings\":[{\"resource_id\":\"string\",\"resource_type\":\"project\",\"role\":\"ProjectOwner\"}]}", Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);

{
  "client_secret": "",
  "service_account": {
    "client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn",
    "created_at": "2026-04-10T15:23:00Z",
    "id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "name": "My Service Account",
    "updated_at": "2026-04-10T15:23:00Z"
  }
}

{
  "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": "UNKNOWN",
    "message": "Internal server error"
  },
  "status": 500
}

Search documentation

API Keys

Organizations

Projects

Users

Invites

Service Accounts

Role Bindings

Create a service account

Parameters

Request body

Responses

API Keys

Organizations

Projects

Users

Invites

Service Accounts

Role Bindings