Session Profiles

What are session profiles?

Session profiles are resources created by the parent organization that allow sessions to be issued with limited scope. 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'

A scope can restrict the target user only when the activity exposes it. CREATE_AUTHENTICATORS_V2 and the API key activities expose activity.params.user_id, so a scope can pin them to a fixed user ID, but no keyword refers to the session holder. A session scoped only to the activity kind enrolls passkeys for the session holder alone while no policy allows the activity and the request does not meet the root quorum. A policy that allows CREATE_AUTHENTICATORS_V2 without an activity.params.user_id condition lets the session target other non-root users. See Activities a user can perform on themselves.

Scope when approving another activity

When a scoped session approves a pending activity with APPROVE_ACTIVITY, the scope is evaluated against the activity being approved, not against APPROVE_ACTIVITY itself. So a session scoped to signing:

activity.type == 'ACTIVITY_TYPE_SIGN_TRANSACTION_V2'

can approve a pending SIGN_TRANSACTION_V2, but cannot approve a pending CREATE_API_KEYS_V2 or UPDATE_ROOT_QUORUM. The session’s authority follows it into the approval, and is judged on what is actually being authorized.

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 scope, 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.

Get started

Features

Reference

Session Profiles

What are session profiles?