AudienceThe 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 TokensErply offers a range of different APIs and microservices. All these APIs require authorization, and authentication information can be passed around in two ways:
- As a session key;
- or as a JSON Web Token (JWT).
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 KeyMost 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:
2. JSON Web TokenA 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:
- 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.
- 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.
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.