--- 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. - `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. This must be the only role the user holds. The platform rejects assigning it alongside any other role. ## 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. - `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. This must be the only role the user holds. The platform rejects assigning it alongside any other role. - `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. --- [API](https://skmtc.net/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.net/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/revisions/e85040b266cc/schema)