Authentication

This section describes how Apex Central authenticates API requests.

Apex Central uses token-based authentication to ensure that only trusted applications can use the APIs. You must create a correctly-defined JSON Web Token (JWT) and include it in each API request to gain access to services and resources.

JWT is an open, industry-standard method for securely transmitting information between parties as a JSON object. The information can be verified and trusted because it is digitally signed.

For more information on JWTs, go to https://jwt.io/introduction/.

Authorization Token Structure

This topic explains the structure of the authorization tokens used to authenticate Apex Central API requests.

A JSON Web Token (JWT) consists of three sections separated by dots (for example, xxxxx.yyyyy.zzzzz).

  • Header: This section contains the following information and is Base64URL-encoded.

    Table 1. JWT Header - Required Information

    Content

    Description

    alg

    Algorithm used to calculate the checksum

    Supported algorithms:

    • HS256 (HMAC SHA256)

    • HS384

    • HS512
    typ

    Type of token

    Important:

    Apex Central only accepts JWTs.

    The following is a sample of a decoded JWT header.

    {
"alg": "HS256",
"typ": "JWT"
}

  • Payload: This section contains statements about the third-party application and additional data, and is Base64URL-encoded.

    Table 2. JWT Payload - Required Information

    Content

    Description

    appid

    Application ID of the third-party application

    You can obtain this value from the Automation API Access Settings screen of the Apex Central console.

    For more information, see Adding an Application.

    iat

    Issued at token generation time

    You must specify this value in the Unix time stamp format (number of seconds since Jan 01 1970 UTC).

    version

    Version of this JWT

    Important:

    Apex Central only accepts V1 JWTs.

    checksum

    Checksum of the request

    For more information, see Checksum Calculation.
    Important:

    Do not include sensitive information in the payload unless the JWT is encrypted.

    The following is a sample of a decoded JWT payload.

    {
"appid": "2E28ED1BABA2-4D10BB13-F4FA-D5D4-31F3",
"iat": 1495187266.6215432,
"version": "V1",
"checksum": "J+CMrBKctcXXuQ68GrpFyS1+FXA4gCKs8crdOGJZ24Q="
}

  • Signature: This section contains the following information and is signed.

    • Encoded header

    • Encoded payload

    • Secret: For Apex Central APIs, the API key is the secret used to generate the signature of the JWT.

    • Algorithm specified in the header

Checksum Calculation

This topic explains how to calculate the checksum used to verify the Apex Central API authorization token.

To prevent third parties from reusing the JWT, include the checksum field in the token. The following information is used to calculate the checksum.

Request

Information

HTTP-Method

HTTP method of the request (in uppercase characters)

  • GET

  • POST

  • PUT

  • DELETE

Raw-URL

Path and query string of the request (in lowercase characters)

  • Example 1:

    • URL of the API:

      https://<Apex_Central_Server>/WebApp/API/AgentResource/ProductAgents?HostName=TestAgent

    • Raw-URL:

      /webapp/API/agentresource/productagents?hostname=testagent

  • Example 2:

    • URL of the Automation API:

      https://<Apex_Central_Server>/WebApp/API/AgentResource/ProductAgents

    • Raw-URL:

      /webapp/API/agentresource/productagents

Important:

If the query string is empty, do not include the "?" character.

Canonical-Request-Headers

List of all request headers that start with API

You must perform the following actions.

  • List the headers in alphabetical order and convert each to the following format.

    LowerCase(Header Name) + ":" + Trim(Header Value)

  • Join the headers using the & separator.

Important:

If no headers start with API, leave the Canonical-Request-Headers value as an empty string.

Request-Body

Body of the request in a UTF-8-encoded JSON string

For the calculated SHA-256 checksum of HTTP-Method + "|" + Raw-URL + "|" + Canonical-Request-Headers + "|" + Request-Body, the checksum field is the base64 string representation of the calculated SHA-256 checksum byte array.