1. Session Keys and JSON Web Tokens

July 14, 2021

On this page

Audience

The following article is primarily oriented to both in-house and third-party developers who want to implement services or applications on top of Erply and need to call different APIs.

Session Keys and JSON Web Tokens

Erply offers a range of different APIs and microservices. All these APIs require authorization, and authentication information can be passed around in two ways:
  1. As a session key;
  2. or as a JSON Web Token (JWT).
Both can be obtained from API call verifyUser, by submitting a user name and password. These are the same credentials that users use to log into Erply back office. The user accounts, passwords and permissions (user groups) can be managed in Erply back office, in the "Settings" menu.

The user name and password belong to a specific Erply account, and the obtained session key (or token) is only valid for the same account. All queries to Erply API need to be made with a combination of client code (the account number) and session key (or token); the session key (or token) on its own is not sufficient.

(It must be additionally noted that without the client code, it is even not possible to know the API endpoint: Erply API's URL is https://<clientcode>.erply.com/api/.)

1. Session Key

Most often, the session key is what you need. It is more widely supported; and Erply API supports only session keys.

The session key is a 44-character alphanumeric random identifier. An example: 
a1ba0833892a396dd1100dd10f481a5f612cb711b67a
 

2. JSON Web Token

A JSON Web Token is a longer string consisting of multiple Base64-encoded parts. The website https://jwt.io/ explains and documents the format and provides an interactive form for inspecting tokens. You can also find libraries for many programming languages there.

A JWT has two good properties:
  1. It contains information. Unlike a session key that is an opaque, random value (as expained above), a JSON Web Token is a "document" that contains user name, Erply account number, information about the session (when it is set to expire), and the user's list of permissions.
  2. It is digitally signed. Therefore, any application anywhere in the world can verify that an Erply JWT is valid. The signature can be checked using the issuing server's public key.
Erply's public key is available at https://id.erply.com/jwt/pubkey.pem. Note that the key can change over time; validating applications should fetch the key from the given URL, not download and store it.

Therefore, if you want to build a service and ensure that only users authenticated in Erply can talk to it, you can make it require a JWT and verify that the provided token is valid.

To complicate matters somewhat, we have two different "flavors" of JWTs in use: Identity JWTs and Erply JWTs.

The differences are explained in a separate article: JSON Web Tokens in Erply.