Overview
As explained in a previous article,- Erply uses both session keys and JSON Web Tokens (JWTs).
- There are two different "flavors" of JWTs in use: Identity JWTs and Erply JWTs.
Identity JWT
Erply's Identity service is a standalone identity management system. It has its own user accounts and its own concept of of "companies" (a company corresponds to an Erply account). A "login with Identity" takes place when user logs into https://apps.erply.com, the launchpad for Erply apps. To log in to Identity, a user must have an email address and a password. These are Identity credentials — these are not the same as a back office user name and password!Today, Identity is slowly being phased out.
Identity is worth mentioning though, because the following services are tightly integrated with Identity and still expect you to configure permissions in Identity:
- Builder (Erply Cloud), a database-as-a-service offering;
- Service Engine.
Identity's permissions system is generic and extensible; applications can define their permissions on-the-fly. In "Identity Admin" (this is the user management panel in apps.erply.com), permissions are just keywords and each user can be associated with any number of those keywords.
This permission management UI has not yet been re-created elsewhere, so if you need to integrate with Builder API, you need to set up user accounts and permissions in Identity, and fetch an Identity JWT to talk to the service.
An Identity JWT can be retrieved from the following places:
- In API verifyUser output, Identity token is returned in field "identityToken".
- In Erply back office, you'll find it in global Javascript variable "jwt" (plugins can use it if needed).
- Identity "Companies" and Erply "Accounts" are linked together, and most likely you already have an auto-generated Company linked to your Erply account.
- Identity users and Erply users can be linked together. Most likely your Erply user account already has a corresponding record in Identity, and you may just need to assign it an email address and a password to start logging in via https://apps.erply.com.
Erply JWTs
These are a newer alternative, intended to replace Identity JWTs.The contents of the token should be more-or-less similar to Identity tokens, but the "perms" array is a work in progress.
We intend to populate the permissions list with all the permissions granted in Erply back office; but right now, the token does not contain any permissions yet, apart from a few special cases.
In the future, we may also have to address the need for "custom permissions", in the same manner that Identity allows to do it (a third-party app can present its custom list of permissions → administrator can grant these permissions to users → JWTs for these users will contain the permission). However, there is no definite roadmap for this feature yet.
JWTs do not make session keys obsolete, we intend to continue using both. (JWTs initially proved useful for ourselves, because they helped us to build certain integrations where the party calling the API might not correspond to any physical user. Session keys must always resolve to a user in database; JWTs are self-descriptive and thus more flexible.)
Converting Session Keys and Tokens
Generally, session keys and JSON Web Tokens (regardless of the flavor) are always exhangeable. If your application wants to call different services, it might find itself in one of the following situations:- It has got a session key, but the particular Erply service requires a JWT.
- It has got a JWT, but the particular API requires a session key.