Skip to main content
POST
/
partner
/
v1
/
sessions
Create a short-lived user session token
curl --request POST \
  --url https://api.machines.cash/partner/v1/sessions \
  --header 'Content-Type: application/json' \
  --header 'X-Partner-Key: <api-key>' \
  --data '
{
  "userId": "user-123",
  "scopes": [
    "kyc.read",
    "kyc.write"
  ]
}
'
{
  "ok": true,
  "data": {
    "sessionToken": "<string>",
    "sessionId": "<string>",
    "userId": "<string>",
    "expiresAt": "2023-11-07T05:31:56Z",
    "scopes": [
      "<string>"
    ]
  },
  "summary": "<string>",
  "errors": [
    {
      "code": "invalid_request",
      "message": "missing required field",
      "field": "<string>"
    }
  ],
  "next": {
    "pollAfterMs": 1,
    "suggestedTool": "<string>",
    "suggestedArgs": {}
  }
}

Authorizations

​
X-Partner-Key
string
header
required

Headers

​
X-Open-Responses
enum<string>

Return Open Responses-compatible output when set (replaces the default response envelope).

Available options:
1,
true
​
X-Open-Responses-Call-Id
string

Tool call id used for function_call_output items when Open Responses mode is enabled.

Minimum string length: 1

Body

application/json
​
userId
string
required

Your user id (must match users.resolve).

Required string length: 1 - 120
Example:

"user-123"

​
scopes
enum<string>[]
required

Scopes to grant to the session token. Deposits and balances do not require extra scopes.

Minimum array length: 1
Available options:
users.read,
users.write,
kyc.read,
kyc.write,
cards.read,
cards.write,
cards.secrets.read,
encryption.read,
encryption.write,
deposits.read,
deposits.write,
withdrawals.write
Example:
["kyc.read", "kyc.write"]
​
walletAddress
string
Example:

"0x2b0f7f2f7c8e4c3d2d3b3f6a8f9b0c1d2e3f4a5b"

​
ttlSeconds
integer

Time-to-live in seconds (default 900).

Required range: 60 <= x <= 86400
Example:

900

​
sessionLabel
string

Optional label for auditing.

Maximum string length: 120

Response

Session created

​
ok
boolean
required
​
data
object
required
​
summary
string
required
​
errors
object[]
required
​
next
object