Acting on Behalf of a Customer

Partners can operate the API on behalf of their customers — onboarding them with a hosted KYC flow, then performing transactions as per normal API requests.

This capability is off by default. It has to be enabled for your account by Blacksheep before any of the endpoints below will accept it — see Request Access.

The bs-on-behalf-of header

To act as a customer, send their account ID in the bs-on-behalf-of header on an otherwise normal, signed API-key request:

Bs-Key-Id: <your partner key id>
Bs-Timestamp: <unix seconds>
Bs-Nonce: <base64 nonce>
Bs-Signature: <ed25519 signature>
Bs-On-Behalf-Of: 1d2b8e7a-…            # the customer account ID

The request is authenticated by your partner key exactly as described in Authentication — the header does not change the signing string. When present, Blacksheep swaps the acting account to the named customer for that request: reads and writes target the customer's account, while the request is still attributed to your partner key for auditing.

The header only works on API-key requests. It is rejected on session (dashboard cookie) requests.

How authorisation works

Every act-as request must meet all of these conditions, or it is rejected:

Every failure returns 403. Each authorised act-as request emits an audit event.

The onboarding flow

1. Get approved. A one-time manual step by Blacksheep (see below).

2. Create a customer. Call account.customer.create with the customer's email. It returns the customer's id — their Blacksheep account ID, allocated up front — along with a hosted url and an expires_at. Store the id against your own customer record now; it's the value you'll pass in bs-on-behalf-of. Send the customer to the url (email it, or embed it in your own flow).

If the url expires before the customer finishes KYC, call account.customer.create again with the same email to get a fresh url and expires_at. The id stays the same across these calls, so you never need to update the value you stored — repeat the call as needed until the customer completes verification.

3. Customer verifies. When the customer completes the hosted KYC, Blacksheep creates their account under the id you already hold and grants your partner account access. Until then the id is a reservation — the account doesn't exist yet, so bs-on-behalf-of requests against it are rejected and it won't appear in account.customer.getMany.

4. Act on their behalf. With the customer's account ID, set bs-on-behalf-of on your signed requests to operate their account — for example:

• create a payout recipient
• add a recipient/customer bank account
• submit a withdrawal or swap
• read balances, transactions, and external accounts

Any endpoint that operates on a customer account accepts the header; endpoints continue to behave exactly as they do for a directly-authenticated account.

Request Access

Approving a partner to create operator accounts and send KYC links is a manual step — we toggle it on per account after a short review.

If you want to onboard and operate accounts on behalf of your customers, email support@blacksheep.money and we'll enable it for you.