Authentication

The Fordefi API uses two authentication mechanisms: bearer tokens and request signing. All requests must be authenticated using a bearer token (JWT). Certain sensitive operations also require signing with the private key associated with the API User.

Bearer token

API users authenticate their requests by passing their access token in the Authorization header with the Bearer prefix.

All API requests are made to the following endpoint:

https://api.fordefi.com/

When making a request, the value for the Authorization header must be in the format Bearer {access token}. For example:

Bearer eyJhbGciOiJFZERTQSIsImtpZCI6ImZ3MFc3aVpocUc0SUEzaXV4ZmhQIiwidHlwIjoiSldUIn0.eyJpc3MiOiJodHRwczovL2FwaS5mb3JkZWZpLmNvbS8iLCJzdWIiOiI2MDlmODVjMi00OWJmLTQwMzItOGM5Yy00NDMyZGEzMzE4MGVAZm9yZGVmaSIsImF1ZCI6WyJodHRwczovL2FwaS5mb3JkZWZpLmNvbS9hcGkvIl0sImV4cCI6MjAxNzI5MDg4NCwiaWF0IjoxNzAxOTMwODg0LCJqdGkiOiJlM2RmNDE0ZS03M2U3LTRkMWEtYmJjYy1iYThiZTE4NDhiOTMifQ.JodHRwczovL2FwaS5mb3JkZWZpLmNvbS8iLCJzdWIiOiI2MDlmODVjMi00OWJmLTQwMzItOGM5Yy00NDMyZGEzMzE4MGVAZm9yZGVmaSIsImF1ZCI6WyJ

All API requests must be made over HTTPS. Calls made over plain HTTP or without theAuthorization header will fail.

Request signing

API requests for sensitive operations, such as creating transactions, require an additional authentication layer.

Prerequisites

Follow the instructions to create an API User and an API Signer, and pair them.

Sign requests

1. Construct the signed message ${path}|${timestamp}|${requestBody}, where:
   • ${path} is the path of the API endpoint for this request. For example, when creating transactions, the path needs to be /api/v1/transactions.
   • ${timestamp} is the time in milliseconds.
   • ${requestBody} is the body of the request.
2. Sign the request body with the API User’s private key, whose public key you have registered with the API Signer. Use the ECDSA signature scheme over the NIST P-256 curve.
3. Pass the signature in a x-signature HTTP header of your POST request, and the timestamp used within the signature in the x-timestamp HTTP header.
4. Pass the API User's access token in the Authorization: Bearer <TOKEN> header, as with regular requests.

You can use the following code sample as the basis for any type of request. The API endpoint and body of the request differ, based on the specific type of request you are creating.

#!bash
 
ACCESS_TOKEN='<Your API User Access Token>'
PRIVATE_KEY_FILE='<Path of your private key PEM file>'
ENDPOINT='/api/v1/transactions'
BODY='{
   // Create Transaction Payload
}'

TIMESTAMP="$(($(date +%s) * 1000))"
SIGNATURE="$(echo -n "${ENDPOINT}|${TIMESTAMP}|${BODY}" | openssl dgst -sha256 -sign ${PRIVATE_KEY_FILE} | base64 | tr -d \\n)"

echo -n "${ENDPOINT}|${TIMESTAMP}|${BODY}"

curl -v "https://api.fordefi.com${ENDPOINT}" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-H "x-signature: ${SIGNATURE}" \
-H "x-timestamp: ${TIMESTAMP}" \
-d "${BODY}"