Skip to main content

The header

Your platform authenticates with its own API key. On its own, a request made with that key acts as your platform: any charge, transfer, or balance read is yours. Send X-Account-Id with an account’s id and the request acts as that account instead.
The header works on any API-key endpoint, not only the Connect ones. There is no separate key per account: one platform key, with X-Account-Id deciding whose behalf a given call is on. A platform key reaches its own account by default, reaches a child account with X-Account-Id, and is rejected for an account that is not its child. A platform key reaches its own account by default, reaches a child account with X-Account-Id, and is rejected for an account that is not its child.
An unread or misspelled header name is not rejected. If the API does not recognize the header, the request runs as your platform and returns success. A caller who omits X-Account-Id, or sends a stale header name, gets a successful call against the wrong party rather than an error. On a checkout this means the charge and the money land in your platform’s balance instead of the account’s.

What it changes

The header changes who a call is made on behalf of, which changes who owns the result.
  • A checkout created with X-Account-Id is a direct charge: the account is the merchant of record, and the sale lands in its balance. See Direct charges.
  • A transfer sent with X-Account-Id moves funds from that account’s balance. See Transfers.
Everything else about creating a checkout or a transfer is unchanged. The header only decides whose balance the call reads from and writes to.

What it does not do

It cannot reach an account that is not yours. Naming an id that is not one of your accounts returns 403, naming the header and the id you sent, rather than acting on it. The check is a direct parentage test: the named account’s parent must be the account your key belongs to, or the request is rejected outright. There is no broader reach through a shared platform, an intermediate account, or any other relationship. An id that does not exist and an id belonging to another platform return the same 403, so the header cannot be used to find out which account ids are real. Your key itself is unaffected: the same request without the header succeeds. It does not grant the account anything it has not been set up for. The header changes who a call runs as; it does not change what that party is allowed to do. An account still needs the capability for a payment method before a checkout run as that account can accept it, and still needs payouts before a withdrawal run as that account will succeed. See Capabilities. It does not change which scope your key needs. The scope check is against your platform key’s own scopes, the same ones it would need calling on its own behalf. Acting as an account does not require a different scope and does not grant one your key does not already have.

Next steps