Manage Users Via API

Create, modify, or remove users via Legito API

Authentication

For authentication Legito API uses a Bearer authentication scheme with JSON Web Token (JWT).

In the JWT bearer authentication flow, your application posts a JWT to the Legito service, asserting its credentials and providing the data of the user that it wishes to impersonate (act on behalf of). Legito validates that the assertion is signed and that your application has the permission to act on behalf of the user.

Prerequisites

First you need to generate an API key and a private key in Legito aplication My account -> Settings -> Developers -> API.

Create a JWT token

To authenticate in the JWT bearer flow, you will need to create a JWT token and include it in authorization header for each of API requests you send to Legito.

In its compact form, JSON Web Tokens consist of three parts separated by dots (.), which are:

  • Header
  • Payload
  • Signature

Header

The header, shown below, specifies the type of the token and algorithm used for signing it. For a Legito service integration, the header structure should always have a type of JWT and use HS256 as its algorithm.

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

Payload

The payload section contains the data for the claims that your application is making. Each legito JWT must contains the following set of claims, as shown below.

ClaimDescription
issAPI key (generated in prerequisites which idetifies your workspace.
iatTimestamp when the JWT was issued, in Unix epoch time format.
expTimestamp when the JWT assertion will expire, in Unix epoch time format. Default and maximal value is one hour from issed time.
{
  "iss": "94afa3c5-a1d5-4657-a8a6-7f968820792c",
  "iat": "1587459071",
  "exp": "1587462671"
}

Signature

The signature part of the JWT is a digital signature that enables Legito to verify that the JWT was created by your application and was not modified since it was created. The first two parts of the JWT are signed with your application’s private key using HS256 digital signature algorithm.

Secret to HS256 algorithm is your generated private key

Example Signature

HMACSHA256(
  base64UrlEncode(header) +
  "." +
  base64UrlEncode(payload),
  $privateKey
);

Creation of authorization header

All of your API requests must include Authorization HTTP header with bearer scheme whitch contains JWT token

Authorization: Bearer <jwtToken>