Developer Hub

Our comprehensive guides and documentation will help you to start working with Minna's subscription management services.

Get Started    

Authentication

Overview

Minna uses OAuth 2OAuth 2 - OAuth 2.0 is the industry-standard protocol for authorization..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 tokenaccess token - A short-lived OAuth2 token that needs to be included in all API requests should be put in the HTTP Authorisation header, as a bearer tokenbearer token - Token that contains the required information to access OAuth 2.0 protected resources.. To generate an access token, you will need to submit a JSON Web Token (JWT) where you prove your identity.

📘

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

Create the RSA key pair

The RSA key pairRSA key pair - Public and private key pair created by the RSA cryptographic algorithm. is used to sign JWTs in order to validate the origin of the request. Below is an example of how to generate an RSA key pair using OpenSSL on a Unix-based system. Minna recommends using at least 2048 bit keys.

openssl genrsa -out mykey.pem 2048

ClientKey Registration

In order to register a client keyclient key - When you are registered for the use of Minnas products and services, a ClientKey is inserted in Minnas system to represent you as a customer, specifying for example your access rights and permissions., 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 RSA key pairRSA key pair - Public and private key pair created by the RSA cryptographic algorithm..

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

After extracting the public key, 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:
Company Description:

Get ClientKey ID

Minna will create your account client keyclient key - When you are registered for the use of Minnas products and services, a ClientKey is inserted in Minnas system to represent you as a customer, specifying for example your access rights and permissions. and respond to your email with your new client key idclient key id - The ClientKeyId is the unique identifier for a ClientKey.. The ClientKeyId should be included in the JWT for registration.

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 Minna supports 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 Minna). 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:
Minna 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, Minna 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>

Updated 6 days ago



Authentication


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.