​
Overview

Below is a brief overview of how to make API calls:
  1. Send your IP address to our support team via email
  2. Create the JWT token according to our specification
  3. Generate the bodyhash by taking the JWT token and hashing it with SHA256 using the API Secret
  4. Sign JWTs with the Private Key
  5. Make the API call
You can find details for each step in the corresponding subsections.

​
1. Send Your IP Address

Send your IP address to our support team via email (support@mansa.com).
This step is required before you can make any API calls. Your IP address must be whitelisted for security purposes.

​
2. Create the JWT Token

The JWT should be structured as follows: 
{
    "typ": "JWT",
    "alg": "ES256"
}
{
    "iss": "your_issuer_name",
    "aud": "Mansa",
    "exp": 1615167712.636125,
    "iat": 1615167412.636125,
    "nbf": 1615167232.636125,
    "uri": "api/endpoint",
    "sub": "API_KEY_PROVIDED_BY_US",
    "bodyHash": "UjPtQ57qFss6Tmq2N+Uh0RY8PDqrlFM2S5BrcoHN4n7epH8f52/hOeECEzl01DvtsQAZIpDZKUwuYqKTBTlhyQ=="
}
Make sure to include the Issuer in the “iss” field and your API Key in the “sub” field.
Details to generate the bodyhash can be found in the next subsection.

​
3. Generate the Bodyhash Signature

To generate the Bodyhash that needs to be included in the JWT token, use the following approach: 
bodyHash: hmac.new(base64.b64decode(API_SECRET_PROVIDED_BY_US), (jwt.uri + requestBody + jwt.nbf), hashlib.sha512)
In this formula, you need to use the API Secret for hashing, not the API Key. Here’s a breakdown of the components:
  • API_SECRET_PROVIDED_BY_US: The API Secret provided by Mansa
  • jwt.uri: The URI of the API endpoint you’re calling
  • requestBody: The serialized JSON string representing the request payload (request body) of your API call
  • jwt.nbf: The “Not Before” claim in the JWT, representing the time before which the JWT must not be accepted for processing
  • hashlib.sha512: The SHA-512 hashing algorithm
Ensure that you use the correct libraries and methods for your programming language to achieve the desired result.

​
4. Sign the JWT Token with the Private Key

The JWT must be signed with an Elliptic Curve Digital Signature Algorithm (ECDSA) using the P-256 curve and the SHA-256 hash algorithm (‘ES256’).

​
5. Make an API Call

Every API request must include the following headers:
  • X-API-Key: The API Key provided to you by Mansa
  • Authorization: Its value should be set to Bearer, followed by a space and the access token, which is a Base64-encoded JWT
{
    "X-API-Key": "your_api_key",
    "Authorization": "Bearer your_base64_encoded_jwt"
}
Make sure to replace “your_api_key” and “your_base64_encoded_jwt” with the actual values provided by Mansa and generated during the JWT creation process, respectively.
These headers should be included in each API call to authenticate and authorize your requests.

​
API Call Rate Limit

The API implements request limits to encourage fair distribution of resources and to uphold system stability. We have established usage guidelines which dictate that a single business is limited to a certain number of requests per minute. If your needs deviate from these constraints, we encourage you to reach out to us. Our team is more than ready to engage in discussions about alternative arrangements that may be more suited to your specific requirements.

​
Example Implementation

Here’s a complete example of how to implement the authentication process: 
import jwt
import hmac
import hashlib
import base64
import time
import json

def create_jwt_token(api_key, api_secret, issuer, uri, request_body):
    # Current timestamp
    now = time.time()
    
    # JWT claims
    claims = {
        "iss": issuer,
        "aud": "Mansa",
        "exp": now + 300,  # 5 minutes from now
        "iat": now,
        "nbf": now,
        "uri": uri,
        "sub": api_key
    }
    
    # Generate bodyhash
    bodyhash_input = uri + request_body + str(int(claims["nbf"]))
    bodyhash = hmac.new(
        base64.b64decode(api_secret),
        bodyhash_input.encode('utf-8'),
        hashlib.sha512
    ).digest()
    
    claims["bodyHash"] = base64.b64encode(bodyhash).decode('utf-8')
    
    # Create JWT (you'll need to sign this with your private key)
    return jwt.encode(claims, algorithm='ES256')
This is a simplified example. In production, you’ll need to properly sign the JWT with your private key and handle all error cases.