Platform Concepts

Business & Access

Understand ownership, identities, and permissions.

Penny resources exist within a Business context. Users and applications authenticate into that context, while roles and permissions determine what they are allowed to do.

BusinessOWNERBusiness EntityORGProgramBOUNDARYUserHUMANApplicationAPIRoleBUNDLEPermissionRULE

Business

A Business represents the top-level customer context within Penny.

Business-owned resources can include:

  • Business Entities;
  • Programs;
  • users;
  • applications;
  • account and issuing resources;
  • access-control configuration.

Retrieve your own Business with GET /businesses/profile.

Business Entities

A Business Entity represents a legal or operating entity associated with a Business. It is the legal owner of the banking and issuing resources underneath it. See Banking & Accounts for how a Linked, Capital, or Control Account belongs to a Business Entity rather than the Business directly.

Penny uses Business Entities wherever activity must be associated with a specific legal entity or compliance context.

Most businesses have a single Business Entity, which Penny uses by default. Retrieve it with GET /businesses/entity.

Programs

A Program is the operating boundary for a financial product — its card products, cards, cardholders, accounts, funding, and spend controls. A Business owns its Programs alongside its Business Entities: the entity is the legal owner of a resource, and the Program is the product it belongs to. See Programs.

Users and applications

Penny distinguishes between human and machine access:

ResourceUsed for
UserA person accessing Penny and performing permitted actions.
ApplicationA server-side system authenticating to Penny APIs.

What it’s for: every call into Penny is made as a user or an application. There is no anonymous or shared-credential access.

How it behaves:

  • Applications authenticate using OAuth 2.0 client credentials. See Authentication.
  • An application’s client_secret is returned once, at creation. Penny does not store it in a retrievable form. If it is lost, rotate it with POST /access/applications/{application_id}/rotate-secret, which invalidates the old secret immediately.
  • Users and applications can hold directly granted permissions and role assignments at the same time. Their effective access is the union of both.

Roles and permissions

Authentication identifies the caller. Permissions determine what that caller can do.

What it’s for: a permission is a resource + action pair (for example {"resource": "account", "action": "read"}). A role bundles permissions so you can assign a named set, such as “Finance auditor”, instead of managing individual grants on each user or application. A role is not a principal: it grants access only through the users and applications it is assigned to.

How it behaves:

  • Penny provides preset roles (global_role_…) with standard permission sets. You assign them exactly like your own roles, but you cannot change them. A preset role grants access only within your own business. List them with GET /access/roles/global.
  • Your business can create custom roles (role_…) when no preset provides the permission set you need.
  • PATCH on a role, application, or user replaces the entire permission set (and, for users and applications, the role set) with what you send. It does not merge.
  • To add or remove a single grant without touching the rest, use the incremental endpoints — POST/DELETE on /access/{applications,users}/{id}/roles/{role_id} and /access/{applications,users,roles}/{id}/permissions/{resource}/{action}. Attaching something already present, or detaching something already absent, succeeds without making a change.

See Access Control for the full permission model.