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 (default sub).

Steps

1. In Studio, open Space Settings → Auth and click Create Strategy.

2. 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.
3. Click Create Strategy. A Space can have any number of JWT strategies, one per issuer.
4. Grant the role(s) the callers will have the capabilities they need, for example execute on an Endpoint's handler Flow.

5. Callers send the token on every request to the Space's App hostname (the *.ligantic.app subdomain 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 its claimValue input. 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 (none and HMAC algorithms are never accepted),
• iss and aud match the strategy,
• exp is 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.