Using JSON Web Tokens

This method is mainly used in cases when you ask users to log in each time they want to interact with the Penneo platform. The users login with their credentials which can be classic credentials i.e. username and password, and a Json Web Token (JWT) is generated that can be used as an access token in the subsequent requests.

Consider the example for creating a JWT when using classic credentials i.e. username and password:

HTTP POST Request

https://app.penneo.com/auth/api/v1/token/password
Content-Type: application/json
{
  "username":"<your username here>",
  "password":"<your password here>"
}

You'll get a token back that you can use when building requests.

📘

Remember to use the correct authentication headers when using JWT

X-Auth-Token: `<your token here>`
Authorization: JWT
Accept: application/json

Handling expired JWT

JWT have an expiration date which is why they are suitable for use when a user has to manually login. However, if you want to use them for a service e.g. robot user performing tasks on behalf of others, it is probably easiest to rely on WSSE credentials. However, if you prefer using JWTs, you need to create a refresh token which has a longer expiration date. You can use this refresh token to generate a new JWT when it expires.

Considering that you want to generate a refresh token when you are using nemid, you can create a refresh token by calling the following endpoint:

HTTP POST Request

https://app.penneo.com/auth/api/v1/token/nemid
{
  "signature":"<base64 encoded signature>",
  "refresh": true
}

You can use the refresh token to create a new JWT, which you can use in subsequent requests:

HTTP POST Request

https://app.penneo.com/auth/api/v1/token/refresh
Content-Type: application/json
{
  "token": "<refresh_token>"
}

📘

Refresh tokens also expire

Refresh tokens can expire if no JWT is generated for a month