What it is for
This is the internal mechanism behind single sign-on between the shell and its modules. It is documented here because integrators ask how it works and because understanding it explains several behaviours that otherwise look arbitrary.
It is not a general-purpose API credential. It cannot be used to call an API, it is not something you mint, and it exists only to carry an authenticated identity from the shell into one module.
What it carries and what is checked
| Claim | Carries | Rejected if |
|---|---|---|
| Issuer | Which shell minted it. | It is not our shell. |
| Audience | Exactly one module. | It is presented to any other module. |
| Subject | The person. | The module will not provision them. |
| Organisation | The tenant they are acting for. | The organisation is not one this module accepts. |
| Expiry | A short lifetime. | It has passed — a replay. |
The signature is verified against a public key set the shell publishes. Modules fetch it; nothing shared and secret passes between them, which is why a module can be deployed and rotated independently of the shell.
Token hand-off
Two consequences you can observe
A session with no current organisation cannot enter any module. The token needs an organisation to name, so the mint refuses. That is the cause of the "signed up and got thrown straight back out" report in Organisations.
Where the token is delivered varies by module. A module running its own authentication library may already own the obvious callback path, so a couple of modules take the token somewhere else. Delivering it to the wrong path produces an authentication error immediately after sign-in rather than a working session.
The audience claim uses the stored key, which for four modules differs from the product name — Accounting is finance, Phony is sdr, Chat is messaging, Projects is pm. Anything reading tokens or entitlement records sees the key. See Platform.
What this does not do
It authenticates a person into a module, nothing else.
The shell mints it. There is no endpoint for third parties.
Short-lived and single-purpose. The module mints its own session afterwards.
One audience each, enforced.
Questions
Can we use erp.io as an identity provider?
No. The model is inbound only, to our own modules.
Where is the public key set?
Published by the shell at a well-known path and fetched by each module.
Does revoking a session revoke module sessions?
Revoking shell sessions is the reliable way to end access. See Security.
Related
How erp.io signs you into a module without a second login: the hand-off token, what the module verifies, and why a module can still ask you to sign in.
SecuritySessions, two-factor authentication, API keys, tenancy isolation and the security controls available to an erp.io administrator.