Session Profiles

Learn how to use session profiles to issue sessions with limited capabilities.

What are session profiles?

Session profiles are resources created by the parent organization that allow sessions to be issued with limited capabilities. When a session is issued with a session profile, the profile’s scope is evaluated on every request made with that session. If the scope evaluates to false, the request is denied.

Session profiles are immutable - once created, they cannot be edited or deleted. If you need to change a session profile, you must create a new one and update your login flows to use the new profile.

Session profiles can be created using the CreateSessionProfile activity, via the public API or the Turnkey dashboard.

Session profile structure

The CreateSessionProfile activity has the following parameters:

• sessionProfileName (required): A human-readable name for the session profile. This name will also be used as the session_type in the resulting session JWT.
• scope (required): A string of policy language that is evaluated on every request made with this session. If the scope evaluates to true, the request is allowed. If it evaluates to false, the request is denied.
• expirationSeconds (optional): The maximum duration in seconds for sessions created with this profile. If not set, the expiration is determined by the value passed into the login activity intent.
• notes (optional): Notes for the session profile.

Scope

The scope field uses the same policy language as policy conditions and MFA conditions. It has access to the same keywords, including activity.type, activity.action, eth.tx, and others.

Examples:

// Allow all activities
true

// Only allow signing activities
activity.action == 'SIGN'

// Allow everything except exporting
activity.action != 'EXPORT'

// Only allow signing with a specific wallet
activity.action == 'SIGN' && wallet.id == '11111111-1111-1111-1111-111111111111'

Expiration

The final session expiration is determined by taking the minimum of the login intent’s expiration and the session profile’s expiration:

• If both are set: the shorter of the two is used
• If only the intent expiration is set: the intent expiration is used
• If only the profile expiration is set: the profile expiration is used
• If neither is set: a default expiration is used (900 seconds / 15 minutes)

This ensures that a session profile’s expiration acts as a ceiling - the login intent can request a shorter session, but never a longer one than the profile allows.

Issuing sessions with a session profile

To issue a session with a session profile, pass the sessionProfileId into any login activity:

• STAMP_LOGIN
• OTP_LOGIN
• OAUTH_LOGIN

If no sessionProfileId is passed, the session is issued as a default read-write session with no scope restrictions. A default session JWT looks like:

{
  "organization_id": "94c1b4e5-2eba-45ad-8c62-8f622fdd3e00",
  "public_key": "02a1b2c3d4e5f6789...",
  "session_type": "SESSION_TYPE_READ_WRITE",
  "exp": 1769204022
}

When a session profile is specified, the JWT includes additional claims:

{
  "organization_id": "94c1b4e5-2eba-45ad-8c62-8f622fdd3e00",
  "public_key": "02a1b2c3d4e5f6789...",
  "session_type": "the-signing-session",
  "session_profile_id": "32f90243-00b9-4172-bef4-62a9c7930849",
  "scope": "activity.action == 'SIGN'",
  "exp": 1769204022
}

Note that session_type is set to the session profile’s name, and scope reflects the scope expression from the profile. The client can decode this JWT to determine what kind of session it has and what activities the session is allowed to perform.

Querying session profiles

Session profiles can be queried using:

• GetSessionProfile: retrieve a single session profile by ID
• GetSessionProfiles: list all session profiles for an organization

Sub-organizations can see session profiles created by their parent organization.

Using session profiles with MFA

Session profiles are commonly used alongside MFA policies to create tiered authentication flows. For example, you can require MFA to obtain a session with elevated capabilities, while allowing a basic session without MFA.

See Satisfying MFA for how sessions interact with MFA authentication methods, and the MFA examples for complete configurations that combine session profiles with MFA policies.