> **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>`: Specifies the maximum number of records to return.
- `skip` `integer <int32>`: Specifies the offset for the first records to return.
- `order` `string`: Specifies the order in which to sort the results.
- `player` `string` _(required)_: The player ID (starts with pla_)
- `expand` `string[]`: Specifies the fields to expand in the response.

### Responses

#### `200`: Successful response.

Body (`application/json`):

- `object` `string` _(required)_
- `url` `string` _(required)_
- `data` `object[]` _(required)_
  - `id` `string` _(required)_
  - `object` `string` _(required)_
  - `createdAt` `integer <int32>` _(required)_
  - `updatedAt` `integer <int32>` _(required)_
  - `isActive` `boolean` _(required)_
  - `address` `string` _(required)_
  - `validAfter` `string` _(required)_
  - `validUntil` `string` _(required)_
  - `account` `object` _(required)_: The account ID.
    - `id` `string` _(required)_
  - `whitelist` `string[]` _(required)_
  - `limit` `integer <int32>` _(required)_
  - `nextAction` `object`
    - `type` `string` _(required)_
    - `payload` `object` _(required)_
      - `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[]`
- `start` `integer <int32>` _(required)_
- `end` `integer <int32>` _(required)_
- `total` `integer <int32>` _(required)_

#### `401`: Error response.

### 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`

### 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`: Successful response.

Body (`application/json`):

- `id` `string` _(required)_
- `object` `string` _(required)_
- `createdAt` `integer <int32>` _(required)_
- `updatedAt` `integer <int32>` _(required)_
- `isActive` `boolean` _(required)_
- `address` `string` _(required)_
- `validAfter` `string` _(required)_
- `validUntil` `string` _(required)_
- `account` `object` _(required)_: The account ID.
  - `id` `string` _(required)_
- `whitelist` `string[]` _(required)_
- `limit` `integer <int32>` _(required)_
- `nextAction` `object`
  - `type` `string` _(required)_
  - `payload` `object` _(required)_
    - `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[]`

#### `401`: Error response.

#### `409`: Error response.

### 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`

### 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`: Successful response.

Body (`application/json`):

- `id` `string` _(required)_
- `object` `string` _(required)_
- `createdAt` `integer <int32>` _(required)_
- `updatedAt` `integer <int32>` _(required)_
- `isActive` `boolean` _(required)_
- `address` `string` _(required)_
- `validAfter` `string` _(required)_
- `validUntil` `string` _(required)_
- `account` `object` _(required)_: The account ID.
  - `id` `string` _(required)_
- `whitelist` `string[]` _(required)_
- `limit` `integer <int32>` _(required)_
- `nextAction` `object`
  - `type` `string` _(required)_
  - `payload` `object` _(required)_
    - `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[]`

#### `401`: Error response.

#### `409`: Error response.

### 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`: Successful response.

Body (`application/json`):

- `id` `string` _(required)_
- `object` `string` _(required)_
- `createdAt` `integer <int32>` _(required)_
- `updatedAt` `integer <int32>` _(required)_
- `isActive` `boolean` _(required)_
- `address` `string` _(required)_
- `validAfter` `string` _(required)_
- `validUntil` `string` _(required)_
- `account` `object` _(required)_: The account ID.
  - `id` `string` _(required)_
- `whitelist` `string[]` _(required)_
- `limit` `integer <int32>` _(required)_
- `nextAction` `object`
  - `type` `string` _(required)_
  - `payload` `object` _(required)_
    - `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[]`

#### `401`: Error response.

#### `409`: Error response.

### 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`: Successful response

Body (`application/json`):

- `id` `string` _(required)_
- `object` `string` _(required)_
- `createdAt` `integer <int32>` _(required)_
- `updatedAt` `integer <int32>` _(required)_
- `isActive` `boolean` _(required)_
- `address` `string` _(required)_
- `validAfter` `string` _(required)_
- `validUntil` `string` _(required)_
- `account` `object` _(required)_: The account ID.
  - `id` `string` _(required)_
- `whitelist` `string[]` _(required)_
- `limit` `integer <int32>` _(required)_
- `nextAction` `object`
  - `type` `string` _(required)_
  - `payload` `object` _(required)_
    - `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[]`

#### `400`: Bad request

#### `401`: Unauthorized

#### `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')
```