Authentication

Overview

We use OAuth 2.0 to secure our APIs and protect user data, see the API security section for more info. To make calls to the API, you must provide an OAuth 2.0 access token with each request. The access token should be put in the HTTP Authorisation header, as a bearer token. To generate an access token, you will need to submit a JSON Web Token (JWT) where you prove your identity.

In order to authenticate to the API, this guide will help you to:

  1. Register a client key
  2. Issue an access token

1. Register a client key

Create the RSA private key

📘

If you already have an RSA key, please skip the first step and continue with ClientKey Registration

The RSA key pair is used to sign JWTs in order to validate the origin of the request. Below is an example of how to generate an RSA private key using OpenSSL on a Unix-based system. We recommend using at least 2048 bit keys.

openssl genrsa -out mykey.pem 2048

ClientKey Registration

In order to register a client key, the public part of your RSA key is required. The public key will be used to validate the origin of your requests. Below is an example of how to extract the public key from the previously generated private key.

openssl rsa -in mykey.pem -pubout > mykey.pub

After extracting the public key, you need to upload it in our Console. To use the Console you first need to register an account. Here is a guide on how to do that.

Uploading public keys are currently only supported in Sandbox. For registering production keys, contact your tech contact or send an email to [email protected] with the information below and with the generated public key attached (called mykey.pub in the example above).

Email Subject : ClientKey Registration
Your name: 
Contact Information:
Company Name:

Get ClientKey ID

We will create your account client key and respond to your request either instantly in the Console (Sandbox) or via e-mail (production) with your new client key id. The ClientKeyId should be included in the JWT for registration.

2. Issue an access token

Prefer to look at some code? Check out the sample code:

Create JWT

The request body of the access token request must be encoded as a JWT. Below you can find an example of how to create and sign the JWT correctly. We recommend creating the JWT using a client library. For more information on JWTs and available libraries, see jwt.io.

The JWT header that we support is the RSA-256. Below is an example of how the header should be specified:

{"alg":"RS256","typ":"JWT"}

The JWT body should contain the following claims (make sure to substitute the <client_key_id> with the one you received from us). Make sure that your epoch timestamps are submitted in seconds.

{
  "aud" : [ "minna.tech" ],
  "exp" : 1574766146, // Epoch timestamp in seconds for when this JWT expires.
  "nbf" : 1574766086, // Epoch timestamp in seconds for when this JWT starts to be valid.
  "clientKeyId" : "<client_key_id>"
}

Note:
We enforces that a JWT can only be valid for 60 seconds, meaning that there can be a maximum of 60 seconds between nbf and exp and the following restriction should hold: (exp - nbf) <= 60.

The JWT signature should be computed from the JWT header, the JWT body, and your RSA private key (using the RS256 algorithm).

The final JWT consists of 3 parts and it will look something like this:

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJtaW5uYS50ZWNoIiwiZXhwIjoxNjAzMzUwMTI1LCJuYmYiOjE2MDMzNTAwNjYsImNsaWVudEtleUlkIjoiPGNsaWVudC1rZXktaWQ-IiwiY2xpZW50TmFtZXNwYWNlIjoiZGVmYXVsdCJ9.AZl6MgwX1nh3sWA6dbIEB78T5kh16hVulVMuSmx1s9SKtzpST402rvCaKcPI4UqXi8k7BjGHtWtrc4fmXmlJJYmeWq581LC1ibFC4PExem5aDSf4erK5Ab2Bt8qrT5dZTL5S0nRAD2FyR-6mOHMFxId21brqNCSxEQE9DHwhjr5pMcpqDskONAPHOSNU0tIL4EqJ8yIpUl_9a_bah5zmyR8uWav0Dj1OgtFCZPfOWEG2GYOktwjW9rcOTi-nSOifSseUXPz6Z6aYH3KfkQmn188IfWRX982ezfqCaatatUopHkl-0lO5dhyHaWZzsrKKwuSJEXaQRsr2gcWDeTyLKw

Request Access Token

After computing the JWT, you should send it in a request to POST /v1/auth/token. If the request is successful, we will respond with a token, its validity in seconds and its type:

{
  "accessToken": "<accessToken>",
  "expiresInSeconds": 3600,
  "tokenType": "Bearer"
}

Use the Access Token

After successfully retrieving a token, the token should then be placed in the Authorization header in subsequent calls to our APIs: Bearer , as in the example below:
Authorization: Bearer <accessToken>


What’s Next