API Authentication

Overview

This section provides information for generating and using authentication headers for the ShieldConex® Orchestration API requests.

Below is the configuration code required by the ShieldConex® Manager to create a new ORCA configuration. See the Quickstart Guide on how to set this up, and the JSON Schema Definitions section for detailed explanations of each property.

🚧

Note

You can only use one authentication method at a time for your ORCA configurations under the same partner.

Also see ORCA Configuration JSON Schema Definitions and Authentication Types.

Proxy Authorization

The difference between the proxy.authorization and authorization per action is that the proxy authorization is required of the target destination(payment processor) while an action requires a partner's credentials to tokenize/decrypt. In the case of ShieldConex®, a template reference that is under a certain partner. For Decryptx® action, it must use the separate authorization (P2PE Manager credentials).

Alternatively, the developer can even pass additional headers as a way of custom authorization that is accepted by the target destination (in this case, the custom header must not be named authorization).

Basic Authentication

📘

Note

Basic Authentication is recommended for testing purposes while in the staging or certification environment. The guide for generating this header for your ShieldConex® or Decryptx® partner can be found here.

First, you need to go to the partner's profile in ShieldConex® or Decryptx® and set API Security to Basic, as shown in the screenshot below.

Setting API Security to Basic determines that all the ORCA configurations and API calls under this specific partner account use Basic only.

ORCA Configuration

As we have set the authentication method to Basic, we must keep it consistent with the actions since we must authenticate against that ShieldConex® or Decryptx® partner. So the next step is to specify the type of authorization basic for your ORCA configuration actions.

{
  "proxy": {
    "method": "post",
    "target": "{The target URL/IP Address}",
    "authorization": {
      "type": "passthrough"
    },
    "logSettings": {
      "requestMasks": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Password",
          "pattern": "all"
        },
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Track2",
          "pattern": "all"
        }
      ],
      "responseMasks": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Result.Secret",
          "pattern": "all"
        }
      ]
    }
  },
  "actions": [
    {
      "type": "shieldconex",
      "authorization": {
        "type": "basic",
        "username": "{partnerID}",
        "password": "{partnerKey}"
      },
      "templateRef": "{templateRef}",
      "method": "tokenize",
      "model": "sync",
      "instructions": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Track2",
          "fieldName": "scx_token_card_number"
        }
      ]
    }
  ]
}

In the case of Decryptx® Parser action, the username and password are the partnerId and partnerKey to the Decryptx® API. P2PE Manager must check Basic as the authentication method.

For example,

  "actions": [
    {
      "type": "parser",
      "authorization": {
        "type": "basic",
        "username": "{partnerID}",
        "password": "{partnerKey}"
      },
      "instructions": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Track2",
          "format": "pan",
          "dataType": "string",
          "default": "mydefault"
        }
      ]
    }
  ],

🚧

Note

Using passthrough for a parser action will result in Authentication required in the Orchestration Logs since it passes ShieldConex® partner credentials from the request as opposed to the Decryptx® credentials. For the reason outlined, it is fine to use passthrough for a shieldconex action. However, it is possible to specify headerName as that header will be extracted for that action. For example,

JSON

{
  ...
  "actions": [
    {
      "type": "parser",
      "authorization": {
        "type": "passthrough",
        "headerName": "my-decryptx-header"
      },
    ...
  ],
  ...
}

Request Configuration

For simplicity, we use the basic authentication header throughout all of the API Examples.

{
  method: "POST",
  headers: {
    "Authorization": "Basic dXNlcm5hbWUxMjM6cGFzc3dvcmQxMjIzMzQ0",
    "Content-Type": "application/json",
  },
  body: {
    "Card" : {
      "Name" : "John Smith",
      "Password" : "supersecret",
      "Track2" : "4444333322221111"
    }
  }
}

HMAC Authentication

ORCA Configuration

First, you need to go to the partner's profile in ShieldConex® or Decryptx® and set API Security to HMAC, as shown in the screenshot below.

Setting API Security to HMAC determines that all the ORCA configurations and API calls under this specific partner account use HMAC only.

For this HMAC authentication example, we use JSON tokenization to demonstrate how to put together the HMAC authentication header and use it in the request configuration in accordance with the HMAC Authentication Guide. If you have trouble generating the HMAC authentication header, see the script.

It's important to note that this header needs to be carefully generated and put together. Otherwise, you will receive an Authentication Required error message.

{
  "proxy": {
    "method": "post",
    "target": "{The target URL/IP Address}",
    "authorization": {
      "type": "passthrough"
    },
    "logSettings": {
      "requestMasks": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Password",
          "pattern": "all"
        },
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Track2",
          "pattern": "all"
        }
      ],
      "responseMasks": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Result.Secret",
          "pattern": "all"
        }
      ]
    }
  },
  "actions": [
    {
      "type": "shieldconex",
      "authorization": {
        "type": "hmac",
        "username": "{partnerID}",
        "secret": "{BASE64_DECODED_KEY_FROM_PARTNER_ACCOUNT}"
      },
      "templateRef": "{templateRef}",
      "method": "tokenize",
      "model": "sync",
      "instructions": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Track2",
          "fieldName": "scx_token_card_number"
        }
      ]
    }
  ]
}

Request Configuration

Below is the request configuration for your application, along with the POST URL. The {configReferenceID} variable is the reference generated from creating the above configuration via the ShieldConex® Manager.

POST https://proxy{-*}.shieldconex.com/api/v1/partners/{partnerID}/configurations/{configReferenceID}

{
  method: "POST",
  headers: {
    "Authorization": "Hmac username=\"WATERFORD\", nonce=\"1l5daa1ju1b7lmljc5p4nev0ve\",  timestamp=1489574949, response=\"7fd904ec88c5dc9217e178bc8e115b950c243197b5116e3e1fc43061eeb846ac\"
",
    "Content-Type": "application/json",
  },
  body: {
    "Card" : {
      "Name" : "John Smith",
      "Password" : "supersecret",
      "Track2" : "4444333322221111"
    }
  }
}

🚧

Note

The generated HMAC_AUTH_HEADER can be used only once per API call.