- App Search Guide: other versions:
- Installation
- Getting started
- Authentication
- Limits
- Users and access
- Guides
- Adaptive relevance events logs reference
- Analytics Tags
- Crawl web content
- Crawl a private network using a web crawler on Elastic Cloud
- Crawl custom fields using proxy
- Curations
- Elasticsearch search
- Elasticsearch index engines
- Create Elasticsearch index engines
- Configure dynamic field mappings and analyzers in an Elasticsearch index engine
- Elasticsearch engines text field conventions
- Facets
- Hierarchical Facets
- Indexing Documents
- Language Optimization
- Log settings
- Meta Engines
- Precision tuning (beta)
- Query Suggestions
- Search UI
- Relevance Tuning
- Result Settings
- Result Suggestions
- Role based access control (RBAC)
- Sanitization, Raw or Snippet
- Search
- Synonyms
- View web crawler events logs
- App Search web crawler
- Web crawler FAQ
- Web crawler reference
- Web crawler events logs reference
- API Reference
- Adaptive relevance API reference (beta)
- Analytics APIs
- Analytics clicks API
- Analytics counts API
- Analytics queries API
- API logs API
- Click API
- Credentials API
- Curations API reference
- Documents API
- Elasticsearch search API
- Engines API
- Log settings API
- Multi search API
- Query suggestion API
- Schema API
- Search API
- Search API boosts
- Search API facets
- Search API filters
- Search API group
- Search API precision (beta)
- Search API result fields
- Search API search fields
- Search API sort
- Search API analytics tags
- Search settings API
- Search Explain API
- Source engines API
- Synonyms API
- Web crawler API reference
- API Clients
- Configuration
- Known issues
- Troubleshooting
Credentials API
editCredentials API
editThe 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
editThe 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
editList Keys
editGenerate 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
editGenerate 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
editYou can create three different types of keys:
Your choice of Key will depend on the endpoint:
Key Name | Key Prefix | Endpoint |
---|---|---|
Public Search Key |
|
Search endpoint only. |
Private API Key |
|
All endpoints except Credentials. It is recommended that you use the Public Search Key when using the Search endpoint. |
Private Admin Key |
|
Credentials endpoint only. |
Private API Key
editPOST <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
editPOST <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
editPOST <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
editYou 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
editDELETE <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 }
On this page
ElasticON events are back!
Learn about the Elastic Search AI Platform from the experts at our live events.
Register now