--- title: "Create an API key" method: POST path: "/v2/api_keys" tags: ["API Keys"] --- # Create an API key `POST /v2/api_keys` Creates an API key. You can bind the key to one or more corpora. A `personal` key has the same permissions as its owner; any other key carries exactly the roles assigned to it with `api_roles`, `corpus_roles`, and `agent_roles`. Callers with the `corpus_administrator`, `administrator`, or `owner` role create any API key. Callers holding only other roles must set `api_key_role` to `personal`. Only a user can create a personal API key; a request authenticated with a machine credential — an API key, app client, or service account — receives a `403` error. :::note For more information about the different types of API keys, see [API Key Management](/docs/security/authentication/api-key-management). ::: ## Headers - `Request-Timeout` integer - `Request-Timeout-Millis` integer ## Request body - CreateApiKeyRequest — Request to create a new API key for authenticating with the platform. - `name` string, required — The human-readable name of the API key. - `api_roles` ApiRole[] — Customer-level roles for this API key. - `api_key_role` 'serving' | 'serving_and_indexing' | 'personal' — The role of the API key. A `personal` key has the same permissions as its owner. A `serving` API key can only perform query type requests on its corpora, and a `serving_and_indexing` key can perform both indexing and query type requests; these two roles are deprecated for creation — assign roles with `api_roles` instead. - `corpus_keys` CorpusKey[] — Deprecated: Use corpus_roles instead. Corpora this API key has roles on. - `corpus_roles` CorpusRole[] — Corpus-specific role assignments for this API key. - `corpus_key` string, required — The key of the corpus this role applies to. - `role` 'owner' | 'administrator' | 'viewer' | 'editor', required — The role assigned for this specific corpus. - `agent_roles` AgentRole[] — Agent-specific role assignments for this API key. - `agent_key` string, required — The key of the agent this role applies to. For the `agent_end_user` role this is an agent alias key, which shares the same shape. - `role` 'agent_administrator' | 'agent_viewer' | 'agent_developer' | 'agent_user' | 'agent_end_user', required — The role assigned for this specific agent. * `agent_administrator` - Full administrative access to the agent including deletion and configuration. * `agent_viewer` - Read-only access to view agent configuration, sessions, events, instructions, and tools. * `agent_developer` - Can modify agent configuration, create/manage sessions, update tools and instructions. * `agent_user` - Limited access to interact with the agent by creating sessions and sending inputs. Cannot view agent configuration or modify settings. * `agent_end_user` - Granted on an alias, lets a user create sessions and send messages through it. They see only their own sessions, and within them only their own messages and the agent's replies. ## Response `201` The response includes the assigned API key ID, name, secret key, enabled status, API key role, and API policy. - ApiKey — An API key used to authenticate and authorize requests to the Vectara platform. - `id` string, required — The ID of the API key. - `name` string, required — The human-readable name of the API key. - `secret_key` string, required — The key used in API requests. Keep the key secure. - `enabled` boolean — Indicates whether the API key is enabled. - `api_roles` ApiRole[] — Customer-level roles for this API key. - `api_key_role` 'serving' | 'serving_and_indexing' | 'personal' — The role of the API key. A `personal` key has the same permissions as its owner. A `serving` API key can only perform query type requests on its corpora, and a `serving_and_indexing` key can perform both indexing and query type requests; these two roles are deprecated for creation — assign roles with `api_roles` instead. - `corpus_roles` CorpusRole[] — Corpus-specific role assignments for this API key. - `corpus_key` string, required — The key of the corpus this role applies to. - `role` 'owner' | 'administrator' | 'viewer' | 'editor', required — The role assigned for this specific corpus. - `agent_roles` AgentRole[] — Agent-specific role assignments for this API key. - `agent_key` string, required — The key of the agent this role applies to. For the `agent_end_user` role this is an agent alias key, which shares the same shape. - `role` 'agent_administrator' | 'agent_viewer' | 'agent_developer' | 'agent_user' | 'agent_end_user', required — The role assigned for this specific agent. * `agent_administrator` - Full administrative access to the agent including deletion and configuration. * `agent_viewer` - Read-only access to view agent configuration, sessions, events, instructions, and tools. * `agent_developer` - Can modify agent configuration, create/manage sessions, update tools and instructions. * `agent_user` - Limited access to interact with the agent by creating sessions and sending inputs. Cannot view agent configuration or modify settings. * `agent_end_user` - Granted on an alias, lets a user create sessions and send messages through it. They see only their own sessions, and within them only their own messages and the agent's replies. - `api_policy` ApiPolicy — The actions a principal can take on the Vectara platform. - `name` string, required — The name of the API role. - `allowed_operations` object, required — The operations the API role allows. Each operation may allow only certain resources, described by a map of resource path to resource values. If the value is null, the operation allows any resource. ## Other responses - `400` — API key creation request was malformed. - `403` — The caller's roles do not allow creating this API key. Callers that hold none of the `corpus_administrator`, `administrator`, or `owner` roles may only create a personal key, and machine credentials — API keys, app clients, and service accounts — may not create personal keys at all. ## Changes - **2026-09-14** `c94fd099d78b` — 1 warning, 1 info - added the new `metrics_viewer` enum value to the `api_roles/items/` response property for the response status `201` - added the new `metrics_viewer` enum value to the request property `api_roles/items/` - **2026-08-08** `e85040b266cc` — 6 breaking, 6 info - added `#/components/schemas/ApiKeyRole` to the `api_key_role` request property `allOf` list - removed the enum value `personal` of the request property `api_key_role` - removed the enum value `serving` of the request property `api_key_role` - removed the enum value `serving_and_indexing` of the request property `api_key_role` - …8 more - **2026-08-05** `fca567a46b3a` — 1 warning, 1 info - added the new `agent_end_user` enum value to the `agent_roles/items/role` response property for the response status `201` - added the new `agent_end_user` enum value to the request property `agent_roles/items/role` [Change history](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/changes/v2/api_keys/post.md) --- [API](https://skmtc.dev/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/revisions/5cd882cb3cda?raw)