> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://useroot.docs.buildwithfern.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://useroot.docs.buildwithfern.com/_mcp/server.

# Create party session token

POST https://api.useroot.com/api/session-tokens/party
Content-Type: application/json

Generate a session token for either payee or payer (party-based approach).

This is the new party endpoint that supports both payees and payers.
It can be used instead of the separate legacy /api/session-tokens endpoint.

This endpoint can only be called with an API token context.
It generates a short-lived JWT token with appropriate scopes based on the party type.

The process:
1. API token authenticates the request
2. Party ID and party type are provided in the request
3. System validates the party exists and belongs to the API token's root entity
4. A session token is created with appropriate scopes based on party type

This allows frontend applications to make authenticated requests on behalf of a specific party.

Reference: https://useroot.docs.buildwithfern.com/api-reference/session-tokens-api/create-party-session-token

## Authentication

- `x-api-key` header (required) — RootPay API key sent in the x-api-key header. Keys are environment-scoped: live_* for production, test_* for sandbox.

## Request

### Body (application/json)

- `party_id` (string, required) — UUID of the party (payee or payer) to create a token for. This will be used as the user identifier in the token.
- `party_type` (enum, required) — Type of party - either 'payee' or 'payer'
  - Allowed values: `payer`, `payee`, `external`

## Response

### 200

Successful Response

- `token` (string, required) — JWT token to be used for further requests
- `expires_in_seconds` (integer, required) — Number of seconds until this token expires
- `scopes` (list of string, required) — Permission scopes granted to this token

## Examples

### Party payee session token response

**Request**

```json
{
  "party_id": "string",
  "party_type": "payer"
}
```

**Response**

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in_seconds": 36000,
  "scopes": [
    "payee_manage"
  ]
}
```

**SDK Code**

```python Party payee session token response
import requests

url = "https://api.useroot.com/api/session-tokens/party"

payload = {
    "party_id": "string",
    "party_type": "payer"
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Party payee session token response
const url = 'https://api.useroot.com/api/session-tokens/party';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"party_id":"string","party_type":"payer"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Party payee session token response
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.useroot.com/api/session-tokens/party"

	payload := strings.NewReader("{\n  \"party_id\": \"string\",\n  \"party_type\": \"payer\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Party payee session token response
require 'uri'
require 'net/http'

url = URI("https://api.useroot.com/api/session-tokens/party")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"party_id\": \"string\",\n  \"party_type\": \"payer\"\n}"

response = http.request(request)
puts response.read_body
```

```java Party payee session token response
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.useroot.com/api/session-tokens/party")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"party_id\": \"string\",\n  \"party_type\": \"payer\"\n}")
  .asString();
```

```php Party payee session token response
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.useroot.com/api/session-tokens/party', [
  'body' => '{
  "party_id": "string",
  "party_type": "payer"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Party payee session token response
using RestSharp;

var client = new RestClient("https://api.useroot.com/api/session-tokens/party");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"party_id\": \"string\",\n  \"party_type\": \"payer\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Party payee session token response
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "party_id": "string",
  "party_type": "payer"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.useroot.com/api/session-tokens/party")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Party payer session token response

**Request**

```json
{
  "party_id": "string",
  "party_type": "payer"
}
```

**Response**

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in_seconds": 36000,
  "scopes": [
    "payer_manage"
  ]
}
```

**SDK Code**

```python Party payer session token response
import requests

url = "https://api.useroot.com/api/session-tokens/party"

payload = {
    "party_id": "string",
    "party_type": "payer"
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Party payer session token response
const url = 'https://api.useroot.com/api/session-tokens/party';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"party_id":"string","party_type":"payer"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Party payer session token response
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.useroot.com/api/session-tokens/party"

	payload := strings.NewReader("{\n  \"party_id\": \"string\",\n  \"party_type\": \"payer\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Party payer session token response
require 'uri'
require 'net/http'

url = URI("https://api.useroot.com/api/session-tokens/party")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"party_id\": \"string\",\n  \"party_type\": \"payer\"\n}"

response = http.request(request)
puts response.read_body
```

```java Party payer session token response
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.useroot.com/api/session-tokens/party")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"party_id\": \"string\",\n  \"party_type\": \"payer\"\n}")
  .asString();
```

```php Party payer session token response
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.useroot.com/api/session-tokens/party', [
  'body' => '{
  "party_id": "string",
  "party_type": "payer"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Party payer session token response
using RestSharp;

var client = new RestClient("https://api.useroot.com/api/session-tokens/party");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"party_id\": \"string\",\n  \"party_type\": \"payer\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Party payer session token response
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "party_id": "string",
  "party_type": "payer"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.useroot.com/api/session-tokens/party")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```