> ## Documentation Index
> Fetch the complete documentation index at: https://turnkey-0e7c1f5b-mfa-sessions-new-structure.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://app.turnkey.com).

## 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](./overview#creating-a-read-write-session).
* `scope` (required): A string of [policy language](/features/policies/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](/features/policies/language) as policy conditions and MFA conditions. It has access to the same keywords, including `activity.type`, `activity.action`, `eth.tx`, and others.

**Examples:**

```ts theme={"system"}
// 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:

```json theme={"system"}
{
  "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:

```json theme={"system"}
{
  "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](../mfa/overview) 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](../mfa/satisfying-mfa#session) for how sessions interact with MFA authentication methods, and the [MFA examples](../mfa/examples) for complete configurations that combine session profiles with MFA policies.