Authentication

Most of the endpoints require an Authorization header with a JWT token in it. To obtain a token you can either make a call to authenticate API as self sign a token with provided private key.

Create Token

post /authentication

This endpoint allows you to create a JWT token

Request

Headers

Name	Type	Value Description
Content-Type *	string	application-json

Body

Name	Type	Value Description
strategy *	string	app-secret
appId *	string	App ID provided by us
appSecret *	string	App Secret provided by us

Response

200: OK

Successful auth

{
  "accessToken": "<JWT token>",
  "name": "You app's name",
  "appId": "Your app id"
}

401: Unauthorized

Successful auth

{
  "name": "NotAuthenticated",
  "message": "Invalid login",
  "code": 401,
  "className": "not-authenticated",
  "data": {
    "message": "Invalid login"
  },
  "errors": {}
}

---

Auth Revalidation

post /authentication

With this endpoint, you can validate the issued token.

Request

Headers

Name	Type	Value Description
Content-Type *	string	application-json
Authorization *	string	Bearer <jwt>

Body

Name	Type	Value Description
strategy *	string	app-token

Response

200: OK

Successful auth

{
  "accessToken": "<JWT token>",
  "name": "You app's name",
  "appId": "Your app id"
}

401: Unauthorized

Successful auth

{
  "name": "NotAuthenticated",
  "message": "Invalid login",
  "code": 401,
  "className": "not-authenticated",
  "data": {
    "message": "Invalid login"
  },
  "errors": {}
}

---

Self Signed Tokens

When you get app credentials from us, along with appId, appSecret we will also provide you with a ECDSA P-256 Primary key. Using this you can sign token yourself using ES256 algorithm. Following is a smple nodejs code for self signed tokens -

import jwt from 'jsonwebtoken';

function getRefrensToken(appId, privateKey) {
  return jwt.sign(
    {
      iss: appId, // appId provided by us
      aud: 'serana',
      sub: appId, // appId provided by us
      auth: {
        entity: 'app',
        strategy: 'app-iss-app-token',
      },
    },
    privateKey,
    {
      algorithm: 'ES256', // required
      expiresIn: '1h', // keep as short as possible and not more then 1 day
    },
  );
}

// appId and private key will be provided by us
const privateKey = `
-----BEGIN PRIVATE KEY-----
SAMPLEKEYxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxyYOUSHALLNOTPASS/
-----END PRIVATE KEY-----
`;
const appId = 'fooApp';

console.log(getRefrensToken(appId, privateKey));

---

Validate Self Signed Token

post /authentication

With this endpoint, you can validate the issued token.

Request

Headers

Name	Type	Value Description
Content-Type *	string	application-json
Authorization *	string	Bearer <jwt>

Body

Name	Type	Value Description
strategy *	string	app-iss-app-token

Response

200: OK

Successful auth

{
  "accessToken": "<JWT token>",
  "name": "You app's name",
  "appId": "Your app id"
}

401: Unauthorized

Successful auth

{
  "name": "NotAuthenticated",
  "message": "Invalid login",
  "code": 401,
  "className": "not-authenticated",
  "data": {
    "message": "Invalid login"
  },
  "errors": {}
}