Skip to main content

Authentication

The finperks Giftcard API requires requests to be signed for authentication. finperks provides a client id and client secret as credentials. These credentials are scoped to the specific API environment and may be scoped further to only supporting specific actions to allow safe usage in accordance to the associated risk for the use case. The secret will never have to be included in plain text in a request, but is only used to create the signature.

The API uses this signature algorithm in addition to transport encryption via HTTPS. More information about HTTPS certificate verification can be found under Accessing the API.

Request Signature​

Authorization header format for API requests

Authorization: FP1-HMAC-SHA256 KeyId=ID, Signature=SIGNATURE

For requests, the API expects a standard HTTP Authorization header with a custom authentication scheme, FP1-HMAC-SHA256.

Replace ID with your client id and SIGNATURE with a signature based on certain parts of the request. The specific calculation method to build the signature is described below.

Example Date header

Date: Wed, 09 Jul 2025 16:17:31 GMT

The signature includes the current time, which must be included in the request's Date header.

When the Authorization header is missing or invalid, the API returns HTTP status 401 with a WWW-Authenticate: FP1-HMAC-SHA256 header and an error.

Webhook Signature​

For webhooks, we provide the signature in a custom header, Fp-Signature.

Fp-Signature header format for webhook requests

Fp-Signature: FP1-HMAC-SHA256 KeyId=ID, Signature=SIGNATURE

ID will be replaced by the key that was used for the Signature to optimize validation during key rotation.

SIGNATURE will be replaced with a signature based on certain parts of the request. The algorithm for calculating the signature is described below. Webhook requests contain a Date header as used in Request Signature.

When receiving webhooks, always verify the signature.

Calculating the Signature​

Calculating the signature means generating a string with certain parameters and then using your client secret to sign the string with HMAC-SHA256. This section describes how the signature can be calculated. It also contains a signature generator which you can use to confirm the correctness of your implementation.

The string to sign contains the parameters in the following order, separated by newlines (line feed characters \n only).

Example String to sign

api.finperks.com:443
POST
/v1/orders

Wed, 09 Jul 2025 16:17:31 GMT
5433c546-82d1-4105-baf7-7243a562273d
9123e49bd48ab640096f65ed7b21fc2a1006a799dad0553a20ec9aff745be887
  • Host and port, separated by a colon, e.g. api.finperks.com:443. The host must match the host in the request's Host-header.
  • HTTP Method, e.g. POST
  • Path, e.g. /v1/orders
  • Query string without question mark
  • Date as specified in the Date header, e.g. Wed, 09 Jul 2025 16:17:31 GMT (make sure the date and your system's clock is correct, it must be within a small window around the current time)
  • Idempotency key as specified in the Idempotency-Key header (see below, may be empty if the header is not used for a request)
  • SHA-256 digest of the request body (SHA-256 of an empty string if the body is empty), e.g. aa4edf67aba250d4cb4fb483835d0e40bad5ef7f17de8f4efa8c2f3eb12688c2

The newlines are always necessary, regardless of whether a value is empty or not, so that number of lines in the string to sign is always the same. Do not add a newline after the body digest. Make sure to only use line feed characters, and no carriage returns. This is important, as we use the same mechanism to calculate the signature to verify your credentials.

The last step is signing the string with your client secret. Use the client secret in the form finperks provides it (do not convert the data to binary).

Example Key: 924f85f0-3581-4678-967a-5eb5615a0a41

Bash Example showing HMAC-SHA256 signing

signature=$(printf "%s" "$string_to_sign" | openssl dgst -sha256 -hmac "$api_key" | sed 's/^.* //')
echo "$signature"

Use the client secret to sign the string using HMAC with SHA-256 as hash function and encode the resulting bytes in hexidecimal form.

With the example string to sign and example key above, you can calculate the following signature:

Example Signature: 0ce8cbdab32f25d12fb0535740ab6993fdc3fd67cf4b5ac14c33588337b36066

Example​

Example Request Headers with signature in the Authorization header

POST /v1/orders HTTP/1.1
Authorization: FP1-HMAC-SHA256 KeyId=6b0dff1a-f729-42d1-9eed-d2f17ef5aedb, Signature=0ce8cbdab32f25d12fb0535740ab6993fdc3fd67cf4b5ac14c33588337b36066
Date: Wed, 09 Jul 2025 16:17:31 GMT
Host: api.finperks.com

Signature Generator​

This signature generator allows you to verify and debug your implementation of the signature algorithm.

Note:

  • Make sure to not have extra whitespace in any of the fields.
  • Make sure you do not accidentally change the newline characters when copying code between the browser and your text editor. E.g. Windows often adds carriage return characters in addition to line feed characters.

The bytes put into the signature must be the same sent with the actual request, so different kinds of newlines and whitespace can invalidate the signature.