Authentication

Most of the Acoustic Content Hub REST API services require authentication before you can access them.
The following instructions describe how to get authentication and then call the authenticated APIs.

1. Authenticating to Acoustic Content

You can authenticate to Acoustic Content by using an Acoustic ID or by using API keys.

• Using an Acoustic ID

  The following curl example shows how to log in to Acoustic Content by calling the login service with the Acoustic ID. curl -v -u [email protected]: password https://content-us-1.content-cms.com/api/login/v1/basicauth

• Using API keys

  API keys provide a more secure way to authenticate into Acoustic Content. Your Administrator can generate multiple API keys that can be shared across applications and can also revoke the API keys at any time. The generated API key is linked to your Acoustic Content account whether the account has federated authentication or not. If you have a federated authentication, you must use the API key to log in to Acoustic Content with the REST APIs or with the wchtools. For more information about creating API keys, see API Authentication
  Log in to Acoustic Content with the REST APIs and wchtools by providing the following credentials:
  User ID: AcousticAPIKey
Password: the value of the API key that was presented to you, when you created the API key in the My Acoustic page.
  The following curl example shows how to log in to Acoustic Content by calling the login service with the API key.
  curl -v -u AcousticAPIKey:{insert your API-key value here}https://content-us-1.content-cms.com/api/login/v1/basicauth
  Where the string AcousticAPIKey is used as your user ID and you must provide your API key value that was presented to you when you created the API key in the My Acoustic page. The response to the login request contains a Set-Cookie header containing the proper x-ibm-dx-user-auth value for the user to set in future requests. The subsequent requests are authenticated with the included x-ibm-dx-user-auth header.

2. Obtaining the API URL for your tenant to use the Acoustic Content API

To make authenticated Acoustic Content REST API calls, you need the API URL for your tenant, for example https://content-eu-4.content-cms.com/api/12345678-9abc-def0-1234-56789abcdef0.
You can get the API URL in one of the following ways:

• From the Acoustic Content user interface

  Go to About in the ribbon and then click Hub information. A pop-up window displays the Content Hub ID and Domain name. Use the Content Hub ID and the Domain name, to construct the API URL.
  In the Acoustic Content API URL, besides the place-holder {DomainName} the place-holder {path} is used which is constructed as {path} = api/{Content hub ID}. Therefore, the API URL to access the Acoustic Content API is constructed as follows: {API URL} = https://{DomainName}/{path}.

• From the Acoustic Content Hub login service

  When you authenticate to Acoustic Content using the Acoustic ID, the call returns the header x-ibm-dx-tenant-base-url, which contains the API URL.
  For example, you would get {DomainName} = content-eu-4.content-cms.com and {path} = api/12345678-9abc-def0-1234-56789abcdef0. In the following API description, replace the {DomainName} and {path} place-holders with your specific data.

3. Obtaining the authentication token with HTTP Basic authentication

To make authenticated Acoustic Content REST API calls, you need a cookie that contains the authentication token.
Note: Although the samples on the right-hand side of the Acoustic Content API documentation mention setting the headers X-IBM-Client-Id and X-IBM-Client-Secret, they are currently not needed. For more information, see the API Keys section.
Log in with the API URL and retrieve the authentication token. For example, login and retrieve the authentication token with the following curl command:
curl -v -c cookie.txt -u [email protected]:password https://{DomainName}/{path}/login/v1/basicauth
This command stores the authentication token in the file cookie.txt.

4. Making authenticated Acoustic Content REST API call

Use the obtained information to call an API. For example, the request https://{DomainName}/{path}/authoring/v1/assets converts to the following command:
curl -b cookie.txt https://content-eu-4.content-cms.com/api/12345678-9abc-def0-1234-56789abcdef0/authoring/v1/assets.
You can find a link in the resources section that provides more examples of authenticated calls to Acoustic Content.

Authenticating with any Acoustic Content API request

Acoustic Content provides a more convenient alternate method to authenticate which can be useful when using applications such as Webhooks.
You can avoid the step of sending in a login request separately and can set the Basic Auth header directly as a part of any request you send to Content. The response includes the Set-Cookie headers containing the proper x-ibm-dx-user-auth value, which is used to authenticate subsequent requests you send.

For example, you can set your credentials and basic auth header in an authoring request as follows:

• when using API Key
  curl -v -u AcousticAPIKey:{insert your API-key value here} https://content-us-1.content-cms.com/api/authoring/v1/assets
• When using Acoustic ID
  curl -v -u [email protected]: password https://content-us-1.content-cms.com/api/authoring/v1/assets

User roles

Each API service operation has a set of user roles that are allowed for the operation. You can call only the service operations that are allowed for the specific role a user has.

The roles are organized in a hierarchy, that means each role in the list below has more rights than the roles following this role. For example, the Editor role has more rights than the Viewer and Anonymous role but fewer rights than Administrator and Manager.

The roles are

• Administrator - can access all functionality including tenant administration tasks such as adding/removing users.
• Manager - can create and manage content model, content, and assets.
• Editor - can create and manage content and assets.
• Viewer - can retrieve content and assets via the authoring and preview APIs, but does not have access to the authoring UI.
• Anonymous - cannot access any authoring functionality.

Preview mode

If instead of using the standard host of Acoustic Content, the host is suffixed with -preview for APIs, Acoustic Content is operated in preview mode. In preview mode, besides accessing published data, Acoustic Content can also return draft data. Accessing Acoustic Content in preview mode requires at least Editor role privileges.

Throughput limits for tenants

Acoustic Content is used simultaneously by multiple customers through their tenants. To process resources for all customers, Acoustic Content limits the load that is imposed by each tenant. The throughput limit for trial and paying customers can be different. If the number of requests that are received by Acoustic Content is below the tenants throughput limit, the requests are processed without delay.

Acoustic Content limits the number of requests per second per tenant, if the number of incoming requests is above the throughput limit. The processing of the requests that are above the limit are delayed for a certain time until they can be processed. If the delay time for processing the requests is excessive, any additional requests are returned with the HTTP status code "429 Too Many Requests". When you write client applications by using the Acoustic Content, you must be aware of the following scenarios:

• Requests from the client application can be returned with an HTTP status code 429. In such cases, the best approach would be to retry the request after some time.
• If a client program issues a high number of requests to Acoustic Content, limit the number of outstanding requests. Limiting the number of outstanding requests reduces the risk that requests are replied with HTTP status code 429. In case the client would issue too many requests per second, the request delay algorithm of Acoustic Content would limit the throughput.

HTTPS settings

Acoustic Content is configured for HTTPS usage. All HTTP requests are redirected to HTTPS. The enabled protocol is TLS 1.2 (strict). Ensure that you connect to Acoustic Content only with clients that support TLS 1.2. Clients that do not support the protocol cannot establish connection.

Note: Some clients that support TLS 1.2 have older protocols that are enabled by default, in this case, change the configuration of your client to include TLS 1.2.

CORS support for API access from client-side JS

Cross-Origin Resource Sharing (CORS) can be used to enable secure cross-domain data transfers in client-side JavaScript. If you are calling Acoustic Content services from client-side JavaScript that is hosted on a different domain, you need to enable CORS for that domain. You must add only domains that require access to the content and assets stored in your Content, such as your web servers or your development environment.

The domain format must be protocol://server:port. Here, the protocol is either http or https, the server is either your server name or its IP address, and the port is the port number of your server, for example, http://my.domain.org:80. You can also use the * wildcard to enable CORS for any domain.

To control the CORS enablement for Acoustic Content, from the menu bar in the Acoustic Content user interface, open Hub Setup and select General Settings and then open the Security tab.