---
title: "Create or resume a compliance customer and mint a scoped session"
method: POST
path: "/compliance/sessions"
tags: ["Compliance"]
---

# Create or resume a compliance customer and mint a scoped session

`POST /compliance/sessions`

## Request

- Base URL: `https://v1.orchestrator.rhinestone.dev/deposit-processor`
- URL: `https://v1.orchestrator.rhinestone.dev/deposit-processor/compliance/sessions`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/rhinestonewtf/apis/deposit-service-api/docs/compliance/sessions/post.ts> (a function with typed inputs; its response is checked against the schema)

Called by the integrator backend. Creates or resumes the provider-neutral compliance customer for the given opaque external customer id, optionally binds a registered smart account, and returns a short-lived browser session bearer. The project API key must never be forwarded to the browser — hand the returned token to the modal instead.

## Headers

- `x-api-key` string: API key for authentication

## Request body

- ComplianceSessionRequestBody
  - `externalCustomerId` string, required: The integrator's stable, opaque end-user identifier. Must reveal no identity data (no email/name/wallet). Stored verbatim within the authenticated project.
  - `smartAccount` string: Ethereum address (0x followed by 40 hex characters)
  - `resumeOnly` boolean: Read-only session: never creates a customer or binds an account. 404 `CUSTOMER_NOT_FOUND` unless the customer exists and is bound to `smartAccount` (or no account is given). Needs `deposits:read`. The bearer is read-only whatever the key may do: it reads status, options, accounts and orders, while `POST /compliance/verification`, `POST /onramp/accounts` and `POST /offramp/orders` answer 403 `READ_ONLY_SESSION`.

## Response `200`

Scoped session token

- ComplianceSessionResponse
  - `externalCustomerId` string, required: The opaque external customer reference, returned only to the authenticated integrator backend.
  - `token` string, required: Short-lived scoped session bearer for the browser.
  - `expiresAt` string, required: ISO-8601 absolute expiry of the session token.

## Other responses

- `400`: Invalid request
- `401`: Authentication required or invalid credential
- `403`: API key lacks the required deposits scope, or the smart account is not registered to the calling project
- `404`: `resumeOnly`: no customer exists for this id, or it is not bound to the requested account
- `409`: The requested smart account is already bound to another customer in this project, or the customer is already bound to a different account and changing it requires an explicit migration
- `500`: Failed to create the compliance session
- `503`: Compliance sessions are paused

## Changes

- **2026-11-06** `aa1767d704fa`: 3 info
  - the endpoint scheme security `internalProjectBearer` was added to the API
  - the endpoint scheme security `tenantApiKey` was added to the API
  - the `header` request parameter `x-api-key` became optional
- **2026-10-13** `992508911684`: 2 info
  - added the new optional request property `resumeOnly`
  - added the non-success response with the status `404`
- **2026-10-08** `9705c2757af7`: 3 warning, 1 info
  - removed the optional property `details` from the response with the `409` status
  - added the new `ACCOUNT_ALREADY_LINKED` enum value to the `code` response property for the response status `409`
  - added the new `ACCOUNT_CHANGE_REQUIRES_MIGRATION` enum value to the `code` response property for the response status `409`
  - the response property `code` became required for the status `409`
- **2026-09-17** `676300ac19ff`: 6 info
  - added the optional property `code` to the response with the `400` status
  - added the optional property `code` to the response with the `401` status
  - added the optional property `code` to the response with the `403` status
  - added the optional property `code` to the response with the `409` status
  - …2 more
- **2026-09-14** `b214307f591f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/rhinestonewtf/apis/deposit-service-api/changes/compliance/sessions/post.md)

---

[API](https://skmtc.dev/rhinestonewtf/apis/deposit-service-api.md) - [All operations](https://skmtc.dev/rhinestonewtf/apis/deposit-service-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rhinestonewtf/apis/deposit-service-api/revisions/aa1767d704fa?raw)