Multi-Business Access | The Penny Inc

Partners and resellers often operate Penny on behalf of other businesses — for example, a platform that issues cards for each of its customers. Instead of holding separate credentials for every business, your application authenticates as your own business and names the business it is acting for on each request with the X-Penny-As-Business header.

When you need this

Use this guide if Penny has set up access grants that let your business act on behalf of one or more other businesses.

If your integration works only with your own business, no header is needed and nothing in this guide applies.

Access grants

An access grant allows your business to act on behalf of another business. It’s given by the business being acted on (the target) to your business.

Provisioned by Penny. Grants are set up by Penny as part of your partner onboarding; they can’t be created or changed through the API. Contact your Penny representative to add, change, or remove one.
Permission-bounded. Each grant lists the permissions your business may use on the target. A request outside those permissions is refused, even if your own application holds them.
Optionally expiring. A grant can carry an expiry time, after which it stops working automatically.

Your own user or application also needs the act_as permission on the business resource. Penny grants it as part of partner onboarding; it cannot be self-assigned. Each delegated request must be within both your application’s permissions and the grant’s.

Acting as another business

Add the X-Penny-As-Business header, set to the target’s business_id, to any request. Penny then runs the request in the target business’s context — reads return the target’s resources, and anything you create belongs to the target.

cURL

curl https://issuing.sandbox.api.thepennyinc.com/cardholders/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Penny-As-Business: business_01a2c4e6-8b3d-7f10-9a2b-8b3d7f109a2b"

How it behaves:

The header is per request. Requests without it — or with your own business_id — act as your own business, so one access token can serve every business you have a grant for.
Delegated requests use the target business’s default program. Resources you create on its behalf are created in that program.
Changes to a grant, including revocation, can take up to a minute to take effect.

When a delegated request is refused

Penny returns 403 Forbidden when:

Cause	What to check
The target business isn’t active.	The `business_id` is correct and the business hasn’t been deactivated, suspended, or closed.
There’s no active, unexpired grant from the target to your business.	The grant exists and hasn’t expired or been revoked — contact your Penny representative.
Your application does not hold `act_as`.	Ask your Penny representative to grant it.
The action is outside the grant.	The grant includes the permission the endpoint requires, and your application holds it too.

A 403 on a delegated request is not retryable until the grant or your permissions change. See Errors & Rate Limits.

Subsidiary businesses

If the businesses you operate are set up as subsidiaries of your own, list them with GET /businesses/profiles/ on Penny Banking. It returns the direct subsidiary profiles of your business, filtered with active or status and paged with page_size and next_page_token: