One key for both APIs
SET API (Platforms) and SET Direct Deposit API · Live since 2026-11-10
The problem
A platform that collects with the SET API and pays people with the SET Direct Deposit API held two kinds of key: a SET API key (set_live_…) for /v1 and a partner key (set_partner_…) for /api/partner. That meant two secrets to store, rotate and pin.
The answer: the direct_deposit scope
A SET API key with the direct_deposit scope also opens the Direct Deposit API, as the same business:
POST /v1/api_keys
{ "scopes": ["read", "write", "direct_deposit"], "label": "Payouts service" }Send it as the Bearer token on /api/partner/*, exactly as you would the partner key. Your existing set_partner_… key keeps working.
Rules
| Case | Answer |
|---|---|
A SET API key without the scope, on /api/partner/* | 403 scope_missing |
| A live key on staging, or a test key on production | 401 api_key_wrong_mode |
| A SET Merchant API key | 403 merchant_no_direct_deposit: Direct Deposit is for platforms that pay others |
| Rotating the partner key, or changing its IP allowlist, with a SET API key | 403 partner_key_required. Only the partner key itself, or a dashboard admin, can do that |
| A key pinned to addresses | Its own allowlist applies on both APIs |
- A key's scopes are never broader than the key that issues it. The first key with
direct_depositcomes from SET. - Rate limits are counted per key, across both APIs.
- The audit log names the key by its prefix, whichever API it called.
Events
Both APIs write to one event list for your business. A few types mean different things on each: payout.payment_processed is a /v1 payout on the SET API, and a payee's cash-out on Direct Deposit. Both say object: "payout".
Every event therefore carries api:
api | Events |
|---|---|
set_api | The SET API's own objects: customers, deposits, transfers, /v1 payouts (ids po_…), API keys, data requests |
direct_deposit | Direct Deposit and Payable Email objects: payee cash-outs, payable_payment.*, payee.*, threshold_deposit.*, address.*, payout_intent.*, key.* |
account | Your account itself: webhook_endpoint.*, the monthly fee or revenue share, ping |
Route on type and api together. Events recorded before the field existed carry it too, and an integration that ignores it works as before. A Payable Email event is direct_deposit whichever API you used to send the payment.