Tips for using the Crownpeak AccessAPI

By Denise Duncan
December 19, 2014

AccessAPI documentation:

http://developer.crownpeak.com/Documentation/AccessAPI/index.html

The endpoint is available for all customers. An API key and username/password is required to use the AccessAPI.

The API key is not linked to a specific user however it does require a Crownpeak user to login with a username and password, just like Volte or CDC. It also applies the ACLs (based on the user's group configuration) to each call in the API. Therefore, we recommend creating a user with only the necessary ACLs. This user-based approach allows us to support Volte & Classic and use cases like server-side apps that work across multiple instances, and import/export tools that they can be used for multiple instances. The user permissions should be limited to the only the necessary areas within the platform and only used when communicating through the AccessAPI.

There are two authentication methods.

The basic method:

The first call should always be to Auth/Authenticate and the last call should always be Auth/Logout to end the user session. Every request should include your AccessAPI key in an 'x-api-key' header including the authenticate and logout requests.

The more secure version:

Uses a "Secret Key" if the client requires it, and should only be used from server-side code. This version helps prevent unauthorized request changes in the body, by man-in-the-middle attacks.

For simplicity every request uses a POST http method. This is also effective for security reasons, since querystrings will not be saved in browser and proxies.

We recommend that you send a Content-Type header with a value of 'application/json'. You can specify an Accept header with a value of 'application/xml' or 'application/json'. JSON will be the default response format.

When working with workflow or user data consider using the Auth/AuthenticateWithCache initial request to load the data with your first request.

For other topics, such as handling Template Ids, Model Ids, and Workflow/step ids, caching the initial results is recommended since the results change infrequently.

In order to route an asset, you will need to know the details of the Workflow and step IDs.

Currently, API keys are rate limited at a speed of 9 requests every 3 seconds, so be mindful of the number of requests you send at one time and account for a response code of 429 if you go over the limit. Look to the code samples for specific ways to handle this condition. This rate limit may change. Also, we do have the ability to modify this rate level per API key. In the long term, we do have plans for moving this endpoint to its own servers like "accessapi.crownpeak.com" when/if traffic/demand increases.

The initial release is meant for "server-to-Crownpeak server" traffic, not "browser-to-Crownpeak server" traffic. CORS support will be added at a later time, which will enable "browser- to-Crownpeak server" traffic using oAuth to generate tokens in-lieu of passing credentials.

Language specific helper libraries will be provided to help out with sample code. These libraries will likely be distributed via package managers (Nuget, NPM) and are meant to help developers learn how to use the AccessAPI and use them in their code.

Denise Duncan

Director of Enablement Services

Crownpeak Technology

comments powered by Disqus