Session Configuration
When authentication is enabled, the platform generates a session payload after a user successfully logs in. You must configure the session structure in the API Modeler to ensure authentication tokens are generated securely and contain the correct payload information.
Core Session Parameters
Section titled “Core Session Parameters”A valid session configuration requires the following settings:
1. User Entity Reference
Section titled “1. User Entity Reference”You must specify which entity in your Data Domain represents your system users (usually named User or Customer). This target entity must have the User semantic module applied to it.
2. Session Secret (secret)
Section titled “2. Session Secret (secret)”A secure, long string used as the cryptographic token to sign and encrypt session payloads. This prevents clients from tampering with session tokens.
3. Session Properties (properties)
Section titled “3. Session Properties (properties)”An array specifying which fields from the User entity should be encoded into the session token payload.
- Required: At least one property must be mapped (typically the user’s primary key ID to identify the user on subsequent requests).
- RBAC Mappings: If your API uses the
RBACauthorization strategy, you must map the property annotated with theUserRolesemantic. This allows the authorization engine to inspect the role on each request.
Session Transports
Section titled “Session Transports”You can configure how the session token is transmitted between the client application and the API. At least one transport must be enabled:
- JWT (JSON Web Token): Encodes session parameters in a standard signed token. The client receives the JWT during login and must supply it in the header of subsequent API requests.
- When to use: Mobile Apps & External Integrations (like iOS/Android apps or automated workflows). Mobile devices do not handle web cookies easily, so passing a text token in request headers is the easiest way to authenticate.
- Cookie: Encodes the session inside a secure cookie that is automatically managed and transmitted by the web browser.
- When to use: Websites & Web Applications (running in a browser). Browsers automatically store and attach cookies to every outgoing request. This is the most secure and easiest option for web builders.
Validation Checklist
Section titled “Validation Checklist”During API design, the platform checks the session settings:
- Missing Secret: Triggers a validation error.
- No Enabled Transports: Triggers a validation error.
- Missing Role Mapping (for RBAC): Triggers an error if RBAC is selected but the role property is not mapped inside
session.properties.