|
| 1 | +[[elasticsearch-connecting-to-es-serverless-endpoint]] |
| 2 | += Connecting to your Elasticsearch Serverless endpoint |
| 3 | + |
| 4 | +[TIP] |
| 5 | +==== |
| 6 | +This page assumes you have already <<elasticsearch-get-started-create-project,created an {es-serverless} project>>. |
| 7 | +==== |
| 8 | + |
| 9 | +Learn how to securely connect to your Elasticsearch Serverless instance. |
| 10 | + |
| 11 | +To connect to your Elasticsearch instance from your applications, client libraries, or tools like `curl`, you'll need two key pieces of information: an API key and your endpoint URL. This guide shows you how to get these connection details and verify they work. |
| 12 | + |
| 13 | +[discrete] |
| 14 | +[[elasticsearch-get-started-create-api-key]] |
| 15 | +== Create a new API key |
| 16 | + |
| 17 | +Create an API key to authenticate your requests to the {es} APIs. You'll need an API key for all API requests and client connections. |
| 18 | + |
| 19 | +To create a new API key: |
| 20 | + |
| 21 | +. On the **Getting Started** page, scroll to **Add an API Key** and select **New**. You can also search for *API keys* in the https://www.elastic.co/guide/en/kibana/current/kibana-concepts-analysts.html#_finding_your_apps_and_objects[global search field]. |
| 22 | ++ |
| 23 | +image::images/create-an-api-key.png[Create an API key.] |
| 24 | +. In **Create API Key**, enter a name for your key and (optionally) set an expiration date. |
| 25 | +. (Optional) Under **Control Security privileges**, you can set specific access permissions for this API key. By default, it has full access to all APIs. |
| 26 | +. (Optional) The **Add metadata** section allows you to add custom key-value pairs to help identify and organize your API keys. |
| 27 | +. Select **Create API Key** to finish. |
| 28 | + |
| 29 | +After creation, you'll see your API key displayed as an encoded string. |
| 30 | +Store this encoded API key securely. It is displayed only once and cannot be retrieved later. |
| 31 | +You will use this encoded API key when sending API requests. |
| 32 | + |
| 33 | +[NOTE] |
| 34 | +==== |
| 35 | +You can't recover or retrieve a lost API key. Instead, you must delete the key and create a new one. |
| 36 | +==== |
| 37 | + |
| 38 | +[discrete] |
| 39 | +[[elasticsearch-get-started-endpoint]] |
| 40 | +== Get your {es} endpoint URL |
| 41 | + |
| 42 | +The endpoint URL is the address for your {es} instance. |
| 43 | +You'll use this URL together with your API key to make requests to the {es} APIs. |
| 44 | +To find the endpoint URL: |
| 45 | + |
| 46 | + |
| 47 | +. On the **Getting Started** page, scroll to **Copy your connection details** section, and find the **Elasticsearch endpoint** field. |
| 48 | +. Copy the URL for the Elasticsearch endpoint. |
| 49 | + |
| 50 | +image::images/copy-connection-details.png[Copy your Elasticsearch endpoint.] |
| 51 | + |
| 52 | +[discrete] |
| 53 | +[[elasticsearch-get-started-test-connection]] |
| 54 | +== Test connection |
| 55 | + |
| 56 | +Use https://curl.se[`curl`] to verify your connection to {es}. |
| 57 | + |
| 58 | +`curl` will need access to your Elasticsearch endpoint and `encoded` API key. |
| 59 | +Within your terminal, assign these values to the `ES_URL` and `API_KEY` environment variables. |
| 60 | + |
| 61 | +For example: |
| 62 | + |
| 63 | +[source,bash] |
| 64 | +---- |
| 65 | +export ES_URL="https://dda7de7f1d264286a8fc9741c7741690.es.us-east-1.aws.elastic.cloud:443" |
| 66 | +export API_KEY="ZFZRbF9Jb0JDMEoxaVhoR2pSa3Q6dExwdmJSaldRTHFXWEp4TFFlR19Hdw==" |
| 67 | +---- |
| 68 | + |
| 69 | +Then run the following command to test your connection: |
| 70 | + |
| 71 | +[source,bash] |
| 72 | +---- |
| 73 | +curl "${ES_URL}" \ |
| 74 | + -H "Authorization: ApiKey ${API_KEY}" \ |
| 75 | + -H "Content-Type: application/json" |
| 76 | +---- |
| 77 | + |
| 78 | +You should receive a response similar to the following: |
| 79 | + |
| 80 | +[source,json] |
| 81 | +---- |
| 82 | +{ |
| 83 | + "name" : "serverless", |
| 84 | + "cluster_name" : "dda7de7f1d264286a8fc9741c7741690", |
| 85 | + "cluster_uuid" : "ws0IbTBUQfigmYAVMztkZQ", |
| 86 | + "version" : { ... }, |
| 87 | + "tagline" : "You Know, for Search" |
| 88 | +} |
| 89 | +---- |
| 90 | + |
| 91 | +Now you're ready to start adding data to your {es-serverless} project. |
0 commit comments