- Erply uses both session keys and JSON Web Tokens (JWTs).
- There are two different "flavors" of JWTs in use: Identity JWTs and Erply JWTs.
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".
- 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.
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.)
- 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.