> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://www.openfort.io/api/mcp` to find what you need.
>
> **Have feedback?** Use `submit_feedback` on the same MCP server.

# Sessions

Session keys: scoped, time-boxed signing permissions granted to an account.

## List session keys of a player

`GET /v1/sessions`

Returns a list of Sessions.

Returns the latest 10 transaction intents for each session.

### Query parameters

- `limit` `integer <int32>`: Maximum number of records to return per page. Defaults to 10.
- `skip` `integer <int32>`: Number of records to skip before the first one returned. Defaults to 0. Combine with `limit` to page through results.
- `order` `string`: Sort direction by creation date: `asc` (oldest first) or `desc`. Defaults to `desc` (newest first).
- `player` `string` _(required)_: The player ID (starts with pla_)
- `expand` `string[]`: Related objects to return in full instead of as IDs.

### Responses

#### `200`: A page of session keys.

Body (`application/json`):

- `object` `string` _(required)_: The type of object. Always `list`.
- `url` `string` _(required)_: Path of the endpoint that produced this page.
- `data` `object[]` _(required)_: The items on this page.
  - `id` `string` _(required)_: Unique identifier of the object. The prefix tells its type, for example `acc_` for accounts.
  - `object` `string` _(required)_: The type of object.
  - `createdAt` `integer <int32>` _(required)_: When the object was created, as Unix epoch seconds.
  - `updatedAt` `integer <int32>` _(required)_: When the session was last updated, as Unix epoch seconds.
  - `isActive` `boolean` _(required)_: Whether the session key is registered on the account and has not been revoked.
  - `address` `string` _(required)_: Address of the session key.
  - `validAfter` `string` _(required)_: Unix timestamp in seconds from which the session key is valid, as a string.
  - `validUntil` `string` _(required)_: Unix timestamp in seconds at which the session key expires, as a string.
  - `account` `object` _(required)_: The account the session key is registered on.
    - `id` `string` _(required)_: Unique identifier of the object. The prefix tells its type, for example `acc_` for accounts.
  - `whitelist` `string[]` _(required)_: Contract addresses the session key may interact with.
  - `limit` `integer <int32>` _(required)_: Maximum number of times the session key can be used.
  - `nextAction` `object`: Present when registering the session key still needs the account owner's signature.
    - `type` `string` _(required)_: What the caller must do next. Currently always `sign_with_wallet`.
    - `payload` `object` _(required)_: Data needed to perform the action, including the hash to sign.
      - `userOp` `unknown`: The userOperation.
      - `userOpHash` `string`: The hashed userOperation.
      - `userOperation` `unknown`: The userOperation.
      - `userOperationHash` `string`: The hashed userOperation.
      - `signableHash` `string`: chain-agnostic hash to sign.
  - `transactionIntents` `object[]`: Transaction intents sent with this session key. IDs unless expanded.
- `start` `integer <int32>` _(required)_: Zero-based offset of the first item on this page (the `skip` you passed, default 0).
- `end` `integer <int32>` _(required)_: Offset just past the last item on this page (`start` plus the page size).
- `total` `integer <int32>` _(required)_: Total number of items matching the query across all pages.

#### `401`: Missing or invalid credentials.

### Example request

```bash
curl 'https://api.openfort.io/v1/sessions?limit=10&skip=0&order=desc&player=pla_48eeba57-2cd5-4159-a2cb-057a23a35e65&expand=transactionIntents'
```

```ts
fetch('https://api.openfort.io/v1/sessions?limit=10&skip=0&order=desc&player=pla_48eeba57-2cd5-4159-a2cb-057a23a35e65&expand=transactionIntents')
```

## Create a session key

`POST /v1/sessions`

Creates a Session.

### Header parameters

- `X-Behalf-Of-Project` `string`: Project ID to act on behalf of (for ecosystem operations).

### Request body (required) (`application/json`)

- `address` `string` _(required)_: The address of the session key.
- `chainId` `integer <int32>` _(required)_: The chain ID. Must be a [supported chain](https://www.openfort.io/docs/configuration/chains).
- `externalOwnerAddress` `string`: If no account exists for a given player, create one with this address.
- `limit` `integer <int32>`: Maximum number of times the session key can be used.
- `optimistic` `boolean`: Set to `true` to indicate that the transactionIntent request should be resolved as soon as possible, after the transactionIntent is created and simulated and before it arrives on chain.
- `policy` `string`: ID of the Policy that defines the gas sponsorship strategy (starts with `pol_`). If no Policy is provided, the own Account native token funds will be used to pay for gas.
- `validAfter` `integer <int32>` _(required)_: The unix timestamp in seconds when the session key becomes valid.
- `validUntil` `integer <int32>` _(required)_: The unix timestamp in seconds when the session key expires.
- `whitelist` `string[]`: The list of whitelisted addresses (contracts the session key can interact with).
- `player` `string`: The player ID (starts with pla_).
- `account` `string`: ID of the Account this TransactionIntent is executed with, if one exists (starts with `acc_` or `dac_`). When providing a Player and ChainID, you can omit this parameter.

### Responses

#### `200`: The created session key. Check `nextAction` for a signature the account owner must provide.

Body (`application/json`):

- `id` `string` _(required)_: Unique identifier of the object. The prefix tells its type, for example `acc_` for accounts.
- `object` `string` _(required)_: The type of object.
- `createdAt` `integer <int32>` _(required)_: When the object was created, as Unix epoch seconds.
- `updatedAt` `integer <int32>` _(required)_: When the session was last updated, as Unix epoch seconds.
- `isActive` `boolean` _(required)_: Whether the session key is registered on the account and has not been revoked.
- `address` `string` _(required)_: Address of the session key.
- `validAfter` `string` _(required)_: Unix timestamp in seconds from which the session key is valid, as a string.
- `validUntil` `string` _(required)_: Unix timestamp in seconds at which the session key expires, as a string.
- `account` `object` _(required)_: The account the session key is registered on.
  - `id` `string` _(required)_: Unique identifier of the object. The prefix tells its type, for example `acc_` for accounts.
- `whitelist` `string[]` _(required)_: Contract addresses the session key may interact with.
- `limit` `integer <int32>` _(required)_: Maximum number of times the session key can be used.
- `nextAction` `object`: Present when registering the session key still needs the account owner's signature.
  - `type` `string` _(required)_: What the caller must do next. Currently always `sign_with_wallet`.
  - `payload` `object` _(required)_: Data needed to perform the action, including the hash to sign.
    - `userOp` `unknown`: The userOperation.
    - `userOpHash` `string`: The hashed userOperation.
    - `userOperation` `unknown`: The userOperation.
    - `userOperationHash` `string`: The hashed userOperation.
    - `signableHash` `string`: chain-agnostic hash to sign.
- `transactionIntents` `object[]`: Transaction intents sent with this session key. IDs unless expanded.

#### `401`: Missing or invalid credentials.

#### `409`: The request conflicts with the current state of the resource.

### Example request

```bash
curl https://api.openfort.io/v1/sessions \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "chainId": 80002,
  "externalOwnerAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "limit": 1000,
  "optimistic": true,
  "policy": "pol_7e07ae30-2a4d-48fa-803f-361da94905dd",
  "validAfter": 10,
  "validUntil": 123512123,
  "whitelist": [
    "0x1234567890abcdef1234567890abcdef12345678"
  ],
  "player": "pla_e0b84653-1741-4a3d-9e91-2b0fd2942f60",
  "account": "acc_e1b24353-1741-4a3d-9e91-2b0fd2942f60"
}'
```

```ts
fetch('https://api.openfort.io/v1/sessions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    address: '0x1234567890abcdef1234567890abcdef12345678',
    chainId: 80002,
    externalOwnerAddress: '0x1234567890abcdef1234567890abcdef12345678',
    limit: 1000,
    optimistic: true,
    policy: 'pol_7e07ae30-2a4d-48fa-803f-361da94905dd',
    validAfter: 10,
    validUntil: 123512123,
    whitelist: ['0x1234567890abcdef1234567890abcdef12345678'],
    player: 'pla_e0b84653-1741-4a3d-9e91-2b0fd2942f60',
    account: 'acc_e1b24353-1741-4a3d-9e91-2b0fd2942f60'
  })
})
```

## Revoke the session session key

`POST /v1/sessions/revoke`

### Header parameters

- `X-Behalf-Of-Project` `string`: Project ID to act on behalf of (for ecosystem operations).

### Request body (required) (`application/json`)

- `address` `string` _(required)_: The address of the session key to revoke.
- `policy` `string`: ID of the Policy that defines the gas sponsorship strategy (starts with `pol_`). If no Policy is provided, the own Account native token funds will be used to pay for gas.
- `optimistic` `boolean`: Whether the transactionIntent is optimistic (resolve before it arrives on chain) or not.
- `chainId` `integer <int32>` _(required)_: The chain ID. Must be a [supported chain](https://www.openfort.io/docs/configuration/chains).
- `player` `string`: The player ID (starts with pla_).
- `account` `string`: ID of the Account this TransactionIntent is executed with, if one exists (starts with `acc_` or `dac_`). When providing a Player and ChainID, you can omit this parameter.

### Responses

#### `200`: The revoked session key.

Body (`application/json`):

- `id` `string` _(required)_: Unique identifier of the object. The prefix tells its type, for example `acc_` for accounts.
- `object` `string` _(required)_: The type of object.
- `createdAt` `integer <int32>` _(required)_: When the object was created, as Unix epoch seconds.
- `updatedAt` `integer <int32>` _(required)_: When the session was last updated, as Unix epoch seconds.
- `isActive` `boolean` _(required)_: Whether the session key is registered on the account and has not been revoked.
- `address` `string` _(required)_: Address of the session key.
- `validAfter` `string` _(required)_: Unix timestamp in seconds from which the session key is valid, as a string.
- `validUntil` `string` _(required)_: Unix timestamp in seconds at which the session key expires, as a string.
- `account` `object` _(required)_: The account the session key is registered on.
  - `id` `string` _(required)_: Unique identifier of the object. The prefix tells its type, for example `acc_` for accounts.
- `whitelist` `string[]` _(required)_: Contract addresses the session key may interact with.
- `limit` `integer <int32>` _(required)_: Maximum number of times the session key can be used.
- `nextAction` `object`: Present when registering the session key still needs the account owner's signature.
  - `type` `string` _(required)_: What the caller must do next. Currently always `sign_with_wallet`.
  - `payload` `object` _(required)_: Data needed to perform the action, including the hash to sign.
    - `userOp` `unknown`: The userOperation.
    - `userOpHash` `string`: The hashed userOperation.
    - `userOperation` `unknown`: The userOperation.
    - `userOperationHash` `string`: The hashed userOperation.
    - `signableHash` `string`: chain-agnostic hash to sign.
- `transactionIntents` `object[]`: Transaction intents sent with this session key. IDs unless expanded.

#### `401`: Missing or invalid credentials.

#### `409`: The request conflicts with the current state of the resource.

### Example request

```bash
curl https://api.openfort.io/v1/sessions/revoke \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "policy": "pol_7e07ae30-2a4d-48fa-803f-361da94905dd",
  "optimistic": true,
  "chainId": 80002,
  "player": "pla_e0b84653-1741-4a3d-9e91-2b0fd2942f60",
  "account": "acc_e1b24353-1741-4a3d-9e91-2b0fd2942f60"
}'
```

```ts
fetch('https://api.openfort.io/v1/sessions/revoke', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    address: '0x1234567890abcdef1234567890abcdef12345678',
    policy: 'pol_7e07ae30-2a4d-48fa-803f-361da94905dd',
    optimistic: true,
    chainId: 80002,
    player: 'pla_e0b84653-1741-4a3d-9e91-2b0fd2942f60',
    account: 'acc_e1b24353-1741-4a3d-9e91-2b0fd2942f60'
  })
})
```

## Send signed userOperationHash to create session

`POST /v1/sessions/{id}/signature`

### Path parameters

- `id` `string` _(required)_: Specifies the unique session ID (starts with ses_).

### Request body (required) (`application/json`)

- `signature` `string` _(required)_: signed userOperationHash by the owner or valid session key
- `optimistic` `boolean`: Set to `true` to indicate that the transactionIntent request should be resolved as soon as possible, after the transactionIntent is created and simulated and before it arrives on chain.

### Responses

#### `200`: The session key, registered once the signature is accepted.

Body (`application/json`):

- `id` `string` _(required)_: Unique identifier of the object. The prefix tells its type, for example `acc_` for accounts.
- `object` `string` _(required)_: The type of object.
- `createdAt` `integer <int32>` _(required)_: When the object was created, as Unix epoch seconds.
- `updatedAt` `integer <int32>` _(required)_: When the session was last updated, as Unix epoch seconds.
- `isActive` `boolean` _(required)_: Whether the session key is registered on the account and has not been revoked.
- `address` `string` _(required)_: Address of the session key.
- `validAfter` `string` _(required)_: Unix timestamp in seconds from which the session key is valid, as a string.
- `validUntil` `string` _(required)_: Unix timestamp in seconds at which the session key expires, as a string.
- `account` `object` _(required)_: The account the session key is registered on.
  - `id` `string` _(required)_: Unique identifier of the object. The prefix tells its type, for example `acc_` for accounts.
- `whitelist` `string[]` _(required)_: Contract addresses the session key may interact with.
- `limit` `integer <int32>` _(required)_: Maximum number of times the session key can be used.
- `nextAction` `object`: Present when registering the session key still needs the account owner's signature.
  - `type` `string` _(required)_: What the caller must do next. Currently always `sign_with_wallet`.
  - `payload` `object` _(required)_: Data needed to perform the action, including the hash to sign.
    - `userOp` `unknown`: The userOperation.
    - `userOpHash` `string`: The hashed userOperation.
    - `userOperation` `unknown`: The userOperation.
    - `userOperationHash` `string`: The hashed userOperation.
    - `signableHash` `string`: chain-agnostic hash to sign.
- `transactionIntents` `object[]`: Transaction intents sent with this session key. IDs unless expanded.

#### `401`: Missing or invalid credentials.

#### `409`: The request conflicts with the current state of the resource.

### Example request

```bash
curl https://api.openfort.io/v1/sessions/ses_4194ad24-c818-4e5c-b003-9cc2aa7df53b/signature \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "signature": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "optimistic": true
}'
```

```ts
fetch('https://api.openfort.io/v1/sessions/ses_4194ad24-c818-4e5c-b003-9cc2aa7df53b/signature', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signature: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
    optimistic: true
  })
})
```

## Returns a player session by session id

`GET /v1/sessions/{id}`

Retrieves the details of a Session that has previously been created.

Returns the latest 10 transaction intents that used this session.

### Path parameters

- `id` `string` _(required)_: Specifies the unique session ID (starts with ses_).

### Query parameters

- `expand` `string[]`: Specifies the fields to expand.

### Responses

#### `200`: The session key.

Body (`application/json`):

- `id` `string` _(required)_: Unique identifier of the object. The prefix tells its type, for example `acc_` for accounts.
- `object` `string` _(required)_: The type of object.
- `createdAt` `integer <int32>` _(required)_: When the object was created, as Unix epoch seconds.
- `updatedAt` `integer <int32>` _(required)_: When the session was last updated, as Unix epoch seconds.
- `isActive` `boolean` _(required)_: Whether the session key is registered on the account and has not been revoked.
- `address` `string` _(required)_: Address of the session key.
- `validAfter` `string` _(required)_: Unix timestamp in seconds from which the session key is valid, as a string.
- `validUntil` `string` _(required)_: Unix timestamp in seconds at which the session key expires, as a string.
- `account` `object` _(required)_: The account the session key is registered on.
  - `id` `string` _(required)_: Unique identifier of the object. The prefix tells its type, for example `acc_` for accounts.
- `whitelist` `string[]` _(required)_: Contract addresses the session key may interact with.
- `limit` `integer <int32>` _(required)_: Maximum number of times the session key can be used.
- `nextAction` `object`: Present when registering the session key still needs the account owner's signature.
  - `type` `string` _(required)_: What the caller must do next. Currently always `sign_with_wallet`.
  - `payload` `object` _(required)_: Data needed to perform the action, including the hash to sign.
    - `userOp` `unknown`: The userOperation.
    - `userOpHash` `string`: The hashed userOperation.
    - `userOperation` `unknown`: The userOperation.
    - `userOperationHash` `string`: The hashed userOperation.
    - `signableHash` `string`: chain-agnostic hash to sign.
- `transactionIntents` `object[]`: Transaction intents sent with this session key. IDs unless expanded.

#### `400`: The request is malformed or a parameter is invalid.

#### `401`: Missing or invalid credentials.

#### `404`: Session not found.

### Example request

```bash
curl 'https://api.openfort.io/v1/sessions/ses_4194ad24-c818-4e5c-b003-9cc2aa7df53b?expand=transactionIntents'
```

```ts
fetch('https://api.openfort.io/v1/sessions/ses_4194ad24-c818-4e5c-b003-9cc2aa7df53b?expand=transactionIntents')
```