Create a client session

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/client-sessions \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acct_123",
  "expiresInSeconds": 600,
  "permissions": [
    "account:read",
    "payments:read",
    "payments:write"
  ]
}
'

{
  "clientSessionId": "session_123",
  "clientSessionToken": "client_session_token_opaque_value_1234567890",
  "apiVersion": "2026-09-09",
  "permissions": [
    "account:read"
  ],
  "expiresAt": "2026-08-28T10:00:00.000Z"
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

POST

client-sessions

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/client-sessions \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acct_123",
  "expiresInSeconds": 600,
  "permissions": [
    "account:read",
    "payments:read",
    "payments:write"
  ]
}
'

{
  "clientSessionId": "session_123",
  "clientSessionToken": "client_session_token_opaque_value_1234567890",
  "apiVersion": "2026-09-09",
  "permissions": [
    "account:read"
  ],
  "expiresAt": "2026-08-28T10:00:00.000Z"
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

Call this from your backend with your app credentials, after your own auth has identified the user. Identify exactly one existing account by accountId or externalUserId. Both are strict lookups: this endpoint never creates or updates a UPA, so create the account through the Partner API first. Grant only the permissions this browser or mobile flow needs; omitted permissions default to account:read. Each permission also requires the matching app module and issuing credential scope. The app secret stays on your backend. Pass the returned clientSessionToken to the client, which exchanges it once for a client bearer token. See Authentication.

Authorizations

Authorization

string

header

required

HTTP Basic auth. Username is the Stableyard app ID. Password is the app secret. The optional Stableyard-Version request header must match the environment pin.

Headers

Stableyard-Version

enum<string>

Optional contract-version assertion. Omit it to use the app environment's pinned version. A different supported version is accepted only after that environment is explicitly migrated.

Available options:

2026-09-09

Body

application/json

Create client session request
Create client session request

Bind the client session to exactly one UPA using either identifier.

accountId

string

required

Stableyard account id for the authenticated app user.

Example:

"acct_123"

externalUserId

string

Partner-owned external user id.

Maximum string length: 128

Example:

"user_123"

expiresInSeconds

integer

default:600

Required range: 60 <= x <= 3600

permissions

enum<string>[]

Least-privilege operations embedded in this account-bound client token. Each permission also requires the matching app module and issuing credential scope.

Required array length: 1 - 6 elements

Account-bound browser/mobile authority granted by the partner backend. This is narrower than the issuing app credential and cannot enable a disabled app product.

Available options:

account:read,

payments:read,

payments:write,

deposits:read,

deposits:write,

vault_payments:write

Response

Client session token

clientSessionId

string

required

Example:

"session_123"

clientSessionToken

string

required

Required string length: 32 - 4096

Example:

"client_session_token_opaque_value_1234567890"

apiVersion

enum<string>

required

Immutable date-based contract recorded on the resource. Historical values may appear on existing records; only versions advertised in x-stableyard-supported-api-versions are accepted for new requests.

Available options:

2026-08-28,

2026-09-09

Example:

"2026-09-09"

permissions

enum<string>[]

required

Account-bound browser/mobile authority granted by the partner backend. This is narrower than the issuing app credential and cannot enable a disabled app product.

Available options:

account:read,

payments:read,

payments:write,

deposits:read,

deposits:write,

vault_payments:write

expiresAt

string<date-time>

required

Introduction

Onboarding

Accounts

Money movement

Activity

Vaults

Client & checkout

Platform

Create a client session

Authorizations

Headers

Body

Response