Connecting

Endpoints

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.

All IBM Cloudant HTTP endpoints must be accessed over TLS and prefaced by https://.

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

Private (internal) endpoints are added to all instances deployed on Dedicated Hardware plan environments. The IBM Cloud Private (internal) network endpoint is shown in the following example:

https://$ACCOUNT.private.cloudantnosqldb.appdomain.cloud

In the previous 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 external endpoint would be de810d0e-763f-46a6-ae88-50823dc85581-bluemix.cloudantnosqldb.appdomain.cloud.

For more information about how to block public network connectivity by using IP allowlisting, see Secure access control.

Service credentials

To generate service credentials for IBM Cloudant by using the IBM Cloud Dashboard, see the Creating an IBM Cloudant instance on IBM Cloud tutorial. To generate service credentials from the IBM Cloud CLI, see Creating an instance with CLI.

The following example shows service credentials for an IBM Cloudant instance:

{
  "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://<username>:<password>@76838001-b883-444d-90d0-46f89e942a15-bluemix.cloudant.com",
  "username": "apikey-v2-58B528DF5397465BB6673E1B79482A8C"
}

The service credentials include the following fields:

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.

Authentication

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 and legacy 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 rather than account-level credentials for programmatic access and replication jobs.

IBM Cloudant Dashboard

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, retrieve, update, 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