Sign in
API Keys

Create an API key

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. :::

post/v2/api_keys

Headers

Request-Timeoutinteger

The platform makes a best effort to complete the request in the specified seconds, or it times out.

Request-Timeout-Millisinteger

The platform makes a best effort to complete the request in the specified milliseconds, or it times out.

Request body

namestring required

The human-readable name of the API key.

api_rolesApiRole[]

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_keysCorpusKey[]

Deprecated: Use corpus_roles instead. Corpora this API key has roles on.

Example request

{
  "corpus_keys": [
    "my-corpus"
  ]
}

Response

The response includes the assigned API key ID, name, secret key, enabled status, API key role, and API policy.

idstring required

The ID of the API key.

namestring required

The human-readable name of the API key.

secret_keystring required

The key used in API requests. Keep the key secure.

enabledboolean

Indicates whether the API key is enabled.

api_rolesApiRole[]

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.

Changes

Changed in 2 of the 8 revisions of this API.617

  • e85040b266cc66See the full diff
    • ▲

      added to the request property allOf list

      request-property-all-of-added

    • ▲

      removed the enum value personal of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value serving of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value serving_and_indexing of the request property

      request-property-enum-value-removed

    • ▲

      the request property type changed from string to no type

      request-property-type-changed

    • ▲

      the response's property type changed from string to no type for status

      response-property-type-changed

    • ○

      request property reactivated

      request-property-reactivated

    • ○

      added to the response property allOf list for the response status

      response-property-all-of-added

    • ○

      removed the personal enum value from the response property for the response status

      response-property-enum-value-removed

    • ○

      removed the serving enum value from the response property for the response status

      response-property-enum-value-removed

    • ○

      removed the serving_and_indexing enum value from the response property for the response status

      response-property-enum-value-removed

    • ○

      response property api_key_role reactivated

      response-property-reactivated

  • fca567a46b3a11See the full diff
    • ●

      added the new agent_end_user enum value to the // response property for the response status

      response-property-enum-value-added

    • ○

      added the new agent_end_user enum value to the request property //

      request-property-enum-value-added