Loading...
Area: Episerver Customer-Centric DXP
Applies to versions: Not applicable

Deployment API authentication

Recommendations [hide]

Authentication

The Deployment API for Episerver Customer-Centric Digital Experience Platform (DXP) authenticates each user request using a pair of client key and a client secret.

You can create one or more credentials with the self-service option in the DXP management portal,  and associate them with DXP environments. Associating a single credential to one or more environments simplifies the authentication process, providing flexibility for API users.

Add API credentials

For every environment that you have access to deploy to, you can add one or more credentials that can be used to deploy through API.

You can add a new API credential, or retrieve existing credentials, on the API tab in the DXP Management Portal. To manage your API credentials, follow these steps:

  1. Open the API tab. A list of existing credentials appears. 

    imageh97ph.png

  2. Click Add API credentials and in the window that appears, enter the name for the credential, select applicable environments and click Save to add a new API credential. 

    Note:  You can add duplicate credential for the same combination of environments. You can use the Name credential as an informatory field in such instances. Also, at least one environment needs to be selected for adding a new credential. 

    Newly added credentials appear in the credentials list. The API secret value is only shown once from the time the credential is added until the next page refresh happens. Upon page refresh, the credential secret is removed.
    imageeong.png

  3. Click on the menu icon imageztfn.png available in each credential to perform operations such as Copy API Key, Copy API Secret and Delete API Credential.

    imagevh0is.png

  • Note: If you happen to lose the API secret or it was not copied as mentioned in the previous step, you need to delete the credential, and add a new credential. 

How it works

HMAC computation

Before issuing a request, the client must compute a hash-based message authentication code (HMAC) that is unique to that request. The HMAC is computed as follows:

  1. A message is assembled by concatenating the following parameters:
    • API Key. This is a unique identifier provided to the client upon registration to use the platform.
    • HTTP request method. GET, POST, DELETE, and so on, as uppercase.
    • HTTP request target. Original request target.
    • Timestamp. Time at which the request was created, UTC in milliseconds from Unix epoch.
    • Nonce. A random, unique identifier, generated by the client.
    • MD5 hash of the HTTP request body.
  2. The message is hashed using a SHA256 based HMAC algorithm to produce a signature. The hashing mechanism uses the API secret as a cryptographic key.

    Note: The secret is never communicated across the Internet.

  3. The bytes representing the signature are converted to a base64 encoded string.

Authorization header

Each request must include an "Authorization" HTTP header, which includes the computed HMAC and other supporting parameters. The value of the header must be in the following format.

epi-hmac <api-key>:<timestamp>:<nonce>:<hmac>

The parameters comprising this header include:

  • API Key. This is a unique identifier provided to the client upon registration to use the platform.
  • Timestamp.Time at which the request was created; UTC in milliseconds from Unix epoch.
  • Nonce. A random, unique identifier, generated by the client.
  • HMAC. The signature computed for the header.

Related topics

Do you find this information helpful? Please log in to provide feedback.

Last updated: Apr 02, 2020

Recommendations [hide]