Jiko provides partners with a username and a password, as well as a shared secret. Partners are provided with a bearer token in the Login response, which must be sent with each request.
Each request made to the partner API needs 3 parts in order for it to be processed:
- An Authorization HTTP header containing the value
Bearer <access_token>Where the access_token is the bearer token given in the Login response.
- An x-jiko-idempotency HTTP header set to a random uuid for this action, in order to signify a unique request to the API from the partner’s perspective.
- An x-jiko-signature HTTP header set to a base64 encoded HMAC-SHA256 hash of
x-jiko-idempotency+request pathname+bodyusing the shared secret as a key.
Below is a Node.js example showing how a potential request could be signed:
const crypto = require("crypto");
const uuid = require("uuid");
const idempotency = uuid.v4();
const pathname = "/api/v1/agreements/";
const body = "";
request.headers["x-jiko-signature"] = crypto
.createHmac("sha256", "shared-secret-here")
.update(idempotency + pathname + body, "utf-8")
.digest("base64");Partner requests will need to be sent from an IP address whitelisted by Jiko. Jiko will verify the request signature by repeating the steps above, additionally checking for possible repeated requests. A request is considered to be repeated if the idempotency key value provided in the x-jiko-idempotency header has been used previously in the past 1 hour.
Bearer tokens have a lifetime of 60 minutes. The partner will need to repeat the login process once a token has expired.