Authenticating to Cloudant

Cloudant supports two types of authentication:

• OAuthAPIKey
• Basic

Prerequisite

For OAuthAPIKey and Basic authentication methods, you must have a Cloudant instance in your IBM Cloud account. If you do not already have a Cloudant instance, create one as follows:

1. Log in to your IBM Cloud account.
2. Navigate to the Cloudant page.
3. Choose a name for your instance and click Create. You are then redirected to that Cloudant instance.

IBM Cloud IAM (OAuthAPIKey)

IBM Cloud Identity and Access Management (IAM) is OAuthAPIKey-based authentication.

To authenticate to IBM Cloud, you need the API Key and the URL of the target Cloudant instance. The API key is exchanged for an IAM access token, which is then used to authorize requests.

Creating Service Credentials

You can obtain the ApiKey and URL connection properties together when creating service credentials for the instance.

To create an IBM Cloudant service credential:

1. Log in to the IBM Cloud dashboard.
2. Navigate to the Menu icon > Resource List, and open your IBM Cloudant service instance.
3. In the menu, click Service credentials.
4. Click New credential. Cloudant displays a Add new credential window.
5. Enter a name for the new credential.
6. Click Add. Your credentials are added to the Service credentials table.
7. Click Actions > View credentials.
8. Extract the values for ApiKey and URL from the JSON service credential blob.
   Save this information for future reference.

Authenticating to Cloudant with OAuthAPIKey

To authenticate to IBM Cloud, set the following connection properties:

• AuthScheme: OAuthAPIKey.
• ApiKey: The API key used to authenticate with IBM Cloud IAM.
• URL: The URL of the target Cloudant instance.
  • For example, https://0c9d3837-8304-4aab-a65a-648169970943-bluemix.cloudantnosqldb.appdomain.cloud

When you connect, the provider extracts the access token and authenticates requests.

IBM Cloudant Legacy (Basic)

To connect via IBM Cloudant Legacy, ensure that you have a valid IBM Cloudant service credential.

To create an IBM Cloudant service credential:

1. Log in to the IBM Cloud dashboard.
2. Navigate to the Menu icon > Resource List, and open your IBM Cloudant service instance.
3. In the menu, click Service credentials.
4. Click New credential. Cloudant displays a Add new credential window.
5. Enter a name for the new credential.
6. Click Add. Your credentials are added to the Service credentials table.
7. Click Actions > View credentials.
8. Extract the values for User and Password from the JSON file.

To authenticate, set AuthScheme to Basic and use the values you just obtained to set the User and Password.

Authenticating to a Local Instance

Cloudant supports authenticating to data in local instances from version 1.1.0 and above.

To authenticate to your local instance, set these parameters:

1. URL: The URL of your local instance. For example: http://localhost:8006
2. User: Your username.
3. Password: Your password.