--- name: Cloudant-secure-connection title: Securing your connection description: '- Programmatically accessing IBM Cloudant through curl or client libraries' last-updated: 2023-04-04 --- > ## Documentation Index > The table of contents for this documentation set is at https://cloud.ibm.com/docs/Cloudant?format=markdown > The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt > Use these files to discover more information as needed. # Securing your connection {: #securing-your-connection-to-cloudant} IBM® Cloudant® for IBM Cloud® is accessed through an HTTP API. This document describes the different parts that you use to connect to IBM Cloudant: - Endpoints (Public and Private) - Service credentials - Authentication - Accessing the IBM Cloudant Dashboard - Programmatically accessing IBM Cloudant through [curl](https://curl.haxx.se/){: external} or client libraries {: shortdesc} ## Endpoints (Public and Private) {: #endpoints-sc} IBM Cloudant is accessed through HTTP API endpoints. The endpoints for an instance are shown in both the URL field of the Service Credentials that are generated for the instance, and in **Account** > **Settings** of the IBM Cloudant Dashboard. Therefore, all IBM Cloudant HTTP endpoints must be accessed over TLS and prefaced by `https://`. ### Public Endpoints {: #public-endpoints-sc} The publicly facing external endpoint is shown in the following example: `https://$ACCOUNT.cloudant.com` All instances created after 1 January 2019 include an `appdomain.cloud` domain endpoint. The publicly facing external endpoint is shown in the following example: `https://$ACCOUNT.cloudantnosqldb.appdomain.cloud` In this example, ACCOUNT is the service name of the service instance user in the URL. An example ACCOUNT is de810d0e-763f-46a6-ae88-50823dc85581-bluemix, and resulting example public endpoint would be de810d0e-763f-46a6-ae88-50823dc85581-bluemix.cloudantnosqldb.appdomain.cloud. ### Private Endpoints {: #private-endpoints-sc} Private (internal) endpoints are added to all instances deployed on Dedicated Hardware plan environments. The IBM Cloud internal network endpoint is shown in the following example: `https://$ACCOUNT.private.cloudantnosqldb.appdomain.cloud` In this example, ACCOUNT is the service name of the service instance user in the URL. An example ACCOUNT is de810d0e-763f-46a6-ae88-50823dc85581-bluemix, and resulting example private endpoint would be de810d0e-763f-46a6-ae88-50823dc85581-bluemix.private.cloudantnosqldb.appdomain.cloud. For more information on Private endpoints, see the [Service Endpoints](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-service-endpoints&format=markdown) documentation. For more information about how to block public network connectivity by using IP allowlisting, see [Secure access control](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-security&format=markdown#secure-access-control). ## Service credentials {: #service-credentials-sc} To generate service credentials for IBM Cloudant by using the IBM Cloud Dashboard, see [Creating an IBM Cloudant instance on IBM Cloud](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-getting-started-with-cloudant&format=markdown). To generate service credentials from the IBM Cloud CLI, see [Creating credentials for your IBM Cloudant service](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-creating-an-ibm-cloudant-instance-on-ibm-cloud-by-using-the-ibm-cloud-cli&format=markdown#creating-an-ibm-cloudant-instance-on-ibm-cloud-by-using-the-ibm-cloud-cli). The following example shows service credentials for an IBM Cloudant instance: ```json { "apikey": "MxVp86XHkU82Wc97tdvDF8qM8B0Xdit2RqR1mGfVXPWz", "host": "76838001-b883-444d-90d0-46f89e942a15-bluemix.cloudant.com", "iam_apikey_description": "Auto generated apikey during resource-key [...]", "iam_apikey_name": "auto-generated-apikey-050d21b5-5f[...]", "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Manager", "iam_serviceid_crn": "crn:v1:staging:public:iam-identity::[...]", "password": "8fb6a16b48903e87b769e7f4968521e85c2394ed8f0e69b2769e56dcb27d2e76", "port": 443, "url": "https://:@76838001-b883-444d-90d0-46f89e942a15-bluemix.cloudant.com", "username": "apikey-v2-58B528DF5397465BB6673E1B79482A8C" } ``` {: codeblock} The service credentials include the following fields: | Field | Purpose | |------|--------| | `username` | The username that is required for applications to access the service instance. | | `password` | The legacy credentials password that is required for applications to access the service instance. This field displays only if the `Use both legacy credentials and IAM` option is chosen. | | `host` | The hostname that is used by applications to locate the service instance. This field displays only if the `Use both legacy credentials and IAM` option is chosen. | | `port` | The HTTPS port number for accessing the service instance on the host. It's 443 as only HTTPS access is allowed by IBM Cloudant. This field displays only if the `Use both legacy credentials and IAM` option is chosen. | | `url` | The HTTPS URL to access the IBM Cloudant instance. If the `Use both legacy credentials and IAM` option is chosen, it also includes the embedded legacy username and password. | | `apikey` | The IAM API key. | | `iam_apikey_description` | Description of the IAM API key. | | `iam_apikey_name` | ID of the IAM API key. | | `iam_role_crn` | The IAM role that the IAM API key has. | | `iam_serviceid_crn` | The CRN of the service ID. | {: caption="Service credential fields" caption-side="top"} ## Authentication {: #authentication-overview-sc} IBM Cloudant has two authentication methods available at provisioning time, either `Use only IAM` or `Use both legacy credentials and IAM`. You can see the details about your legacy credentials in the service credentials only if the `Use both legacy credentials and IAM` authentication method is chosen. The credentials display on the Service credentials tab for your instance. For more information, see the [IAM guide](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-managing-access-for-cloudant&format=markdown) and [legacy authentication](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-work-with-your-account&format=markdown#authentication) document for details about using either style of authentication. The IBM Cloudant team recommends you use IAM access controls for authentication whenever possible. If you're using IBM Cloudant legacy authentication, you must use [API keys](https://cloud.ibm.com/docs/apis/cloudant/cloudant-gen1#intro){: external} rather than account-level credentials for programmatic access and replication jobs. {: important} ## IBM Cloudant Dashboard {: #ibm-cloudant-dashboard-sc} You can open the IBM Cloudant Dashboard for your instance by going to the Manage tab of the IBM Cloud Dashboard instance details page. You can use either `Launch` or `Launch Cloudant Dashboard` to open the dashboard in a new browser tab. You can do the following tasks by using the IBM Cloudant Dashboard: - Monitor your current consumption of the instance. - Perform create, read, update, and delete on IBM Cloudant databases, documents, and indexes. - Set up and view replication jobs. - View active tasks. - View and update account information like provisioned throughput capacity, announcements, CORS, and settings. ## Programmatic access {: #programmatic-access-sc} ### Command line (curl) {: #command-line-curl-sc} You can leverage the curl command-line utility to access the IBM Cloudant HTTPS API. For more information about IBM Cloudant legacy authentication, see the [API & SDK reference](https://cloud.ibm.com/docs/apis/cloudant/cloudant-gen1). In the API reference examples, you find details on supplying a username and password to access the IBM Cloudant API with curl. If you use IBM Cloud IAM authentication, you must first get an IBM Cloud IAM token by using an API key. Then, you pass the IAM token to the IBM Cloudant instance to authenticate. For more information, see [Passing an IBM Cloud IAM token to authenticate with a service's API](https://cloud.ibm.com/docs/account?topic=account-iamapikeysforservices&format=markdown#token_auth){: external} tutorial. You can't use an IAM API key directly to authenticate against IBM Cloudant. {: note} ### Client libraries {: #client-libraries-overview-sc} IBM Cloudant has official client libraries for Java™, Node.js, Python, Swift, and Mobile. For more information, see the [client libraries documentation](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-client-libraries&format=markdown#client-libraries) to access the libraries, and see examples for connecting to an IBM Cloudant instance from each.