IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

› ›

Credentials API

edit

Credentials API

edit

The Credentials endpoint enables API based management of your various access credentials.

Credentials refer to your API Keys.

You can create, delete, view, and scope your API Keys.

Authentication

edit

The credentials endpoint requires a Private Admin Key.

A Private Admin Key is not generated for you upon account creation, so you must create one.

The key begins with admin- and is required within all of your requests.

Visit Manage Credentials within your dashboard to generate it:

Private Admin Key - Generate your own

You must generate the first key on your own.

With that key, you can create other Private Admin Keys.

Read API Keys

edit

List Keys

edit

Generate details for all keys.

The output supports pagination, defaulting to 25 items at a time.

GET <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/credentials

Example - A GET request for all available keys.

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/credentials' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer admin-xxxxxxxxxxxxxxxx'

Example Response

{
  "meta": {
    "page": {
      "current": 3,
      "total_pages": 1,
      "total_results": 1,
      "size": 25
    }
  },
  },
  "results": [
    {
      "name": "my-private-key",
      "key": "private-lasda0ha9gah9g8ahs9h",
      "type": "private",
      "read": true,
      "write": false,
      "access_all_engines": true
    },
    {
      "name": "my-search-key",
      "key": "search-lasda0ha9gah9g8ahs9h",
      "type": "search",
      "access_all_engines": false,
      "engines": [
        "my-second-engine"
      ]
    },
    {
      "name": "my-admin-key",
      "key": "admin-lasda0ha9gah9g8ahs9h",
      "type": "admin"
    }
  ]
}

List Key

edit

Generate details for one key.

Note that the name field is not the key itself, but the name that it has been provided.

GET <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/credentials/[API_KEY_NAME]

Example - A GET request for information about my-private-key.

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/credentials/my-private-key' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer admin-xxxxxxxxxxxxxxxx'

Example Response

{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 1,
      "size": 25
    }
  },
  "results": [
    {
      "name": "my-private-key",
      "key": "private-lasda0ha9gah9g8ahs9h",
      "type": "private",
      "read": true,
      "write": false,
      "access_all_engines": true
    }
  ]
}

Create New API Key

edit

You can create three different types of keys:

Your choice of Key will depend on the endpoint:

Key Name	Key Prefix	Endpoint
Public Search Key	`public-`	Search endpoint only.
Private API Key	`private-`	All endpoints except Credentials. It is recommended that you use the Public Search Key when using the Search endpoint.
Private Admin Key	`admin-`	Credentials endpoint only.

Private API Key

edit

POST <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/credentials

name (required): A name for your new key. It can contain letters, numbers or dashes. Limited to 64 characters.
type (required): To generate a Private API Key, the type must be private.
read (required): Can be true or false. If true, the key can read from the engine. If false, the key can not.
write (required): Can be true or false. If true, the key can write to an engine. If false, the key can not.
access_all_engines (optional): Considers all present and future engines. Can be true or false. If true, do not include engines. If false, you must include engines.
engines (optional): If access_all_engines is set to false, provide the engines that the key is permitted to access.

Example - A POST request to create a Private API Key named reading-private-key with read only access to my-second-engine.

curl -X POST '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/credentials' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer admin-xxxxxxxxxxxxxxxx' \
-d '{
  "name": "reading-private-key",
  "type": "private",
  "read": true,
  "write": false,
  "access_all_engines": false,
  "engines": [
    "my-second-engine"
  ]
}'

Example Response

{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 1,
      "size": 25
    }
  },
  "results": [
    {
      "name": "reading-private-key",
      "key": "private-newprivatereadingkey",
      "type": "private",
      "read": true,
      "write": false,
      "access_all_engines": false,
      "engines": [
        "my-second-engine"
      ]
    }
  ]
}

Public Search Key

edit

POST <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/credentials

name (required): A name for your new key. It can contain letters, numbers or dashes. Limited to 64 characters.
type (required): To generate a Public Search Key, type must be search.
access_all_engines (optional): Considers all present and future engines. Can be true or false. If true, do not include engines. If false, you must include engines.
engines (optional): If access_all_engines is set to false, provide the engines that the key is permitted to access.

Example - A POST request to create a Public Search Key named public-searching-key with search access to my-first-engine and my-second-engine.

curl -X POST '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/credentials' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer admin-xxxxxxxxxxxxxxxx' \
-d '{
  "name": "public-searching-key",
  "type": "search",
  "access_all_engines": false,
  "engines": [
    "my-first-engine",
    "my-second-engine"
  ]
}'

Example Response

{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 1,
      "size": 25
    }
  },
  "results": [
    {
      "name": "public-searching-key",
      "key": "search-newpublicsearchingkey",
      "type": "search",
      "access_all_engines": false,
      "engines": [
        "my-first-engine",
        "my-second-engine"
      ]
    }
  ]
}

Private Admin Key

edit

POST <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/credentials

name (required): A name for your new key. It can contain letters, numbers or dashes. Limited to 64 characters.
type (required): To generate a Private Admin Key, type must be admin.

Example - A POST request to create a Private Admin Key named private-admin-key.

curl -X POST '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/credentials' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer admin-xxxxxxxxxxxxxxxx' \
-d '{
  "name": "private-admin-key",
  "type": "admin"
}'

Example Response

{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 1,
      "size": 25
    }
  },
  "results": [
    {
      "name": "reading-private-key",
      "key": "admin-newprivateadminkey",
      "type": "admin"
    }
  ]
}

Update API Key

edit

You are unable to change the type of a key!

Updating an existing key.

PUT <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/credentials/[API_KEY_NAME]

name (required): You can provide a new name for your new key. It can contain letters, numbers or dashes. Limited to 64 characters.
read (required): Only accepted if the key is a Private API Key. Can be true or false. If true, the key can read from the engine. If false, the key can not.
write (required): Only accepted if the key is a Private API Key. Can be true or false. If true, the key can write to an engine. If false, the key can not.
access_all_engines (optional): Considers all present and future engines. Can be true or false. If true, do not include engines. If false, you must include engines.
engines (optional): If access_all_engines is set to false, provide the engines that the new key can access.

Example - A PUT request to update my-private-key so that it has access to all engines.

curl -X PUT '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/credentials/my-private-key' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer admin-xxxxxxxxxxxxxxxx' \
-d '{
  "name": "my-private-key",
  "type": "private",
  "read": true,
  "write": false,
  "access_all_engines": true
}'

Example Response

{
  "meta": {
    "page": {
      "current": 1,
      "total_pages": 1,
      "total_results": 1,
      "size": 25
    }
  },
  "results": [
    {
      "name": "my-private-key",
      "key": "private-sameoldprivatekey",
      "type": "private",
      "access_all_engines": true
    }
  ]
}

Delete API Keys

edit

DELETE <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/credentials/[API_KEY_NAME]

Example - A DELETE request to destroy my-private-key.

curl -X DELETE '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/credentials/my-private-key' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer admin-xxxxxxxxxxxxxxxx'

Example Response

{
  "deleted": true
}

« Click API Curations API reference »