> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinecone.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a service account
> Create a service account with optional initial role bindings. The `client_secret` in the response is shown only once; store it securely.
Grant roles with `role_bindings`: `organization`-scoped bindings omit `resource_id`, while `project`-scoped bindings include the project `resource_id`. Service accounts may receive any organization- or project-scoped role (see Role). Bindings are not returned in the response.
Repeating the same request may create duplicate service accounts.
```bash curl theme={null}
PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
curl "https://api.pinecone.io/admin/service-accounts" \
-H "X-Pinecone-Api-Version: 2026-04" \
-H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \
-d '{
"name": "ci-prod",
"role_bindings": [
{
"resource_type": "project",
"resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58",
"role": "DataPlaneEditor"
}
]
}'
```
```json curl theme={null}
{
"service_account": {
"id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"name": "ci-prod",
"client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn",
"created_at": "2026-04-10T15:23:00Z",
"updated_at": "2026-04-10T15:23:00Z"
},
"client_secret": "8p-kkC23XOWvkCosKq-BOn3G74qp__rBcDMxc82iB4gfzRvuhSCRBKM7C5Q7TAzj"
}
```
## OpenAPI
````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/service-accounts
openapi: 3.0.3
info:
title: Pinecone Admin API
description: >
Provides an API for managing a Pinecone organization and its resources,
including projects, API keys, organization users and invites, service
accounts, and role bindings.
contact:
name: Pinecone Support
url: https://support.pinecone.io
email: support@pinecone.io
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
version: 2026-04
servers:
- url: https://api.pinecone.io
description: Production API endpoints
security:
- BearerAuth: []
tags:
- name: API Keys
description: Actions that manage API Keys.
- name: Organizations
description: Actions that manage organizations.
- name: Projects
description: Actions that manage projects.
- name: Users
description: Actions that manage users.
- name: Invites
description: Actions that manage invites.
- name: Service Accounts
description: Actions that manage service accounts.
- name: Role Bindings
description: Actions that manage role bindings.
paths:
/admin/service-accounts:
post:
tags:
- Service Accounts
summary: Create a service account
description: >
Create a service account with optional initial role bindings. The
`client_secret` in the response is shown only once; store it securely.
Grant roles with `role_bindings`: `organization`-scoped bindings omit
`resource_id`, while `project`-scoped bindings include the project
`resource_id`. Service accounts may receive any organization- or
project-scoped role (see Role). Bindings are not returned in the
response.
Repeating the same request may create duplicate service accounts.
operationId: create_service_account
parameters:
- in: header
name: X-Pinecone-Api-Version
description: Required date-based version header
required: true
schema:
default: 2026-04
type: string
style: simple
requestBody:
description: The service account to create.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateServiceAccountRequest'
examples:
ci-service-account:
summary: Service account with project bindings
value:
name: ci-prod
role_bindings:
- resource_id: a2f7dddb-1597-4eff-9f71-535fde243f58
resource_type: project
role: DataPlaneEditor
org-service-account:
summary: Service account with an organization binding
value:
name: org-automation
role_bindings:
- resource_type: organization
role: OrgManager
required: true
responses:
'201':
description: Service account created.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceAccountWithSecret'
'400':
description: Bad request. The request body included invalid request parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
index-metric-validation-error:
summary: Validation error
value:
error:
code: INVALID_ARGUMENT
message: >-
Bad request. The request body included invalid request
parameters.
status: 400
'401':
description: 'Unauthorized. Possible causes: Invalid API key.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unauthorized:
summary: Unauthorized
value:
error:
code: UNAUTHENTICATED
message: Invalid API key.
status: 401
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
internal-server-error:
summary: Internal server error
value:
error:
code: UNKNOWN
message: Internal server error
status: 500
4XX:
description: Unexpected error on request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
CreateServiceAccountRequest:
type: object
properties:
name:
example: ci-prod
description: The human-readable name of the service account.
type: string
minLength: 1
maxLength: 80
role_bindings:
description: >-
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. Not returned in
the response.
type: array
items:
$ref: '#/components/schemas/RoleBindingInput'
minItems: 0
maxItems: 100
required:
- name
ServiceAccountWithSecret:
example:
client_secret: 8p-kkC23XOWvkCosKq-BOn3G74qp__rBcDMxc82iB4gfzRvuhSCRBKM7C5Q7TAzj
service_account:
client_id: l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn
created_at: '2026-04-10T15:23:00.000Z'
id: f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c
name: My Service Account
updated_at: '2026-04-10T15:23:00.000Z'
description: >-
A service account with a newly issued OAuth `client_secret`. The secret
is returned only once and cannot be retrieved later.
type: object
properties:
service_account:
$ref: '#/components/schemas/ServiceAccount'
client_secret:
description: >-
The OAuth client secret. Returned exactly once. Treat this value as
a credential — store it securely and never log it.
type: string
required:
- service_account
- client_secret
ErrorResponse:
example:
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
description: The response shape used for all error responses.
type: object
properties:
status:
example: 500
description: The HTTP status code of the error.
type: integer
error:
example:
code: INVALID_ARGUMENT
message: >-
Index name must contain only lowercase alphanumeric characters or
hyphens, and must not begin or end with a hyphen.
description: Detailed information about the error that occurred.
type: object
properties:
code:
description: >-
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`.
x-enum:
- 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
- UNPROCESSABLE_ENTITY
type: string
message:
example: >-
Index name must contain only lowercase alphanumeric characters
or hyphens, and must not begin or end with a hyphen.
type: string
details:
description: >-
Additional information about the error. This field is not
guaranteed to be present.
type: object
required:
- code
- message
required:
- status
- error
RoleBindingInput:
description: >-
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.
type: object
properties:
resource_type:
example: project
description: |-
The kind of resource scope a role binding applies to.
Possible values: `organization`, `project`.
x-enum:
- organization
- project
type: string
resource_id:
description: >-
Project UUID. Required when `resource_type` is `project`; omit for
`organization` scope.
type: string
role:
example: ProjectOwner
description: A role assigned to a principal at a resource scope.
x-enum:
- OrgOwner
- OrgManager
- OrgMember
- OrgBillingAdmin
- ProjectOwner
- ProjectManager
- ProjectMember
- ProjectEditor
- ProjectViewer
- ControlPlaneEditor
- ControlPlaneViewer
- DataPlaneEditor
- DataPlaneViewer
type: string
required:
- resource_type
- role
ServiceAccount:
example:
client_id: l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn
created_at: '2026-04-10T15:23:00.000Z'
id: f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c
name: My Service Account
updated_at: '2026-04-12T09:11:00.000Z'
description: A service account. The OAuth `client_secret` is not included.
type: object
properties:
id:
description: >-
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.
type: string
format: uuid
name:
description: A short human-readable label, set by the caller at creation time.
type: string
minLength: 1
maxLength: 80
client_id:
description: >-
The OAuth client ID used by the service account to obtain access
tokens. Used only for OAuth token exchange.
type: string
created_at:
description: The date and time the service account was created.
type: string
format: date-time
updated_at:
description: >-
The date and time of the service account's most recent metadata
update.
type: string
format: date-time
required:
- id
- name
- client_id
- created_at
- updated_at
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >
An [access
token](https://docs.pinecone.io/guides/organizations/manage-service-accounts#retrieve-an-access-token)
must be provided in the `Authorization` header using the `Bearer`
scheme.
````