Security

Security schemas

Below are the different security schemas for the API and the webhooks.

API access oauth2

The API uses OAuth2 with client credentials grant for access. Replace YOUR_CLIENT_ID, YOUR_CLIENT_SECRET and YOUR_SELECTED_SCOPES.

curl --request POST \
  --url http://api.opencard.local/oauth/token \
  --header 'accept: application/json' \
  --header 'content-type: multipart/form-data; boundary=---011000010111000001101001' \
  --form grant_type=client_credentials \
  --form client_id=YOUR_CLIENT_ID \
  --form client_secret=YOUR_CLIENT_SECRET \
  --form scope=YOUR_SELECTED_SCOPES

To obtain access to all scopes, use *

--form scope=*

Available scopes are listed below.

accounts-read
accounts-write
account-users-read
account-users-write
account-statistics-read
clients-read
clients-write
public-records-read
account-tpas-read
account-tpas-write
account-tpa-signatories-write
account-tpa-signatories-read
account-tpa-signatories-delete
organizations-read
organizations-write
webhooks-write
webhooks-read
webhook-events-read
webhook-headers-read
webhook-headers-write
webhook-headers-delete
files-read
card-holders-write
card-holders-delete
card-holders-read
card-issuers-read
billings-read
billings-write
receipts-write
environmental-impacts-read

Webhook

To authenticate the webhook request you can use either the X-Data-Signature header or use one of the predefined security schemas that OpenCard support.

X-Data-Signature:
You can use the header value x-data-signature to validate the payload of the webhook and to validate it is sent from OpenCard.

x-data-signature is sha256 hmac of the payload and the webhook secret:

$xDataSignature = hash_hmac('sha256', <json_payload>, <webhook_secret>)
if($xDataSignature !== $_SERVER['HTTP_X_DATA_SIGNATURE']) {
	header("HTTP/1.1 401 Unauthorized");
  exit;
}

using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(<webhook_secret>)))
{
  byte[] hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(<json_payload>));
  string xDataSignature = BitConverter.ToString(hash).Replace("-", "").ToLower();

  if (xDataSignature != GetRequestHeader("HTTP_X_DATA_SIGNATURE"))
  {
    Console.WriteLine("HTTP/1.1 401 Unauthorized");
    Environment.Exit(0);
  }
}

const crypto = require('crypto');

const webhookSecret = /* Your webhook secret */;
const jsonPayload = /* Your JSON payload */;

const hmac = crypto.createHmac('sha256', <webhook_secret>);
const hash = hmac.update(<json_payload>).digest('hex');
const xDataSignature = hash.toLowerCase();

if (xDataSignature !== getRequestHeader('HTTP_X_DATA_SIGNATURE')) {
    console.log('HTTP/1.1 401 Unauthorized');
    process.exit(0);
}

Authentication header
Select "use authentication" when configuring your webhooks. This allows you to select from 3 different authentication schemes:

Key / value HTTP header
Basic auth
Oauth2, client credential grant