How to Authenticate Requests with a JWT
This guide shows you how to let an external system call a Space's App (for example, an Endpoint, see How to Create an Endpoint) with a bearer JWT issued by its own identity provider.
Prerequisites
- Admin access to the Space.
- JWT authentication turned on for the Space. If the JWT type isn't offered when you create a strategy, contact your administrator.
- The identity provider's JWKS URL, the issuer (
iss) and audience (aud) its tokens carry, and the claim that identifies the caller (defaultsub).
Steps
- In Studio, open Space Settings → Auth and click Create Strategy.
Select type JWT and fill in:
- JWKS URL — the endpoint publishing the provider's signing keys. Localhost and private IP addresses are not accepted.
- Issuer — the expected
iss. It selects the strategy for a token, so it must be unique among the Space's JWT strategies. - Audience — the expected
aud. - Client ID Claim — the claim that identifies the caller. Leave empty for
sub. - Default Space Role — optional; see Identities.
- Click Create Strategy. A Space can have any number of JWT strategies, one per issuer.
- Grant the role(s) the callers will have the capabilities they need, for example
executeon an Endpoint's handler Flow. Callers send the token on every request to the Space's App hostname (the
*.ligantic.appsubdomain or a custom domain):GET /orders/123 Host: acme.ligantic.app Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6...
Result: A request with a validated token is authenticated as a Space identity. A request that fails validation gets 401. See Validation.
Identities
A validated token resolves to a Space identity through the value of its client ID claim.
- With a default Space role, the first request for an unknown claim value creates a Space identity with that role. Later requests reuse it.
- Without a default Space role, only pre-configured identities can authenticate. Open Space Settings → Users → Space Identities and click Create Space Identity: select the JWT strategy, a role, and enter the Claim Value. A Flow can do the same with Auth - Space Identity Create (
auth:space-identity:create), passing the claim value into itsclaimValueinput. A claim value maps to one identity per strategy; removing the identity frees the value. The Space Identities list shows each identity's authentication strategy and claim value.
The resolved Space identity is the request's actor for authorisation, the audit log, and rate limiting (the same per-identity limit as other Space identities).
Validation
On every request the App picks the JWT strategy whose issuer matches the token's iss and checks:
- the signature against the strategy's JWKS (
noneand HMAC algorithms are never accepted), issandaudmatch the strategy,expis present and not passed,- the client ID claim is present,
- the claim value maps to a Space identity (or the strategy has a default role).
A request that fails any check gets 401 and never reaches a Flow. No session cookie is issued, so each request must carry the token. Requests without a bearer token are handled by the Space's other strategies as usual. JWT authentication is only available through the App, not the public API.
Publish a new signing key at the JWKS URL before you sign tokens with it; the App can only accept keys that the URL publishes. If the JWKS URL becomes unreachable, the App keeps accepting tokens for a short time from keys it already has, then rejects requests until the URL recovers.