Authentication

Penny uses OAuth 2.0 client credentials for server-to-server API authentication.

Your backend exchanges an application’s client ID and secret for an access token, then sends that token with each Penny API request.

Before you start

You need a Penny application with a client ID and client secret.

Penny provisions your first application during onboarding. After that, your administrators create and manage applications through the Access API.

Each application has its own permissions. A valid access token only allows the operations granted to that application.

See Access Control for users, applications, roles, and permissions.

Request an access token

Exchange your application credentials for a token using the Banking API host for your environment. The token endpoint accepts a JSON body or an application/x-www-form-urlencoded body with the same fields.

curl -X POST https://sandbox.api.thepennyinc.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'
# Or, as a form-encoded body
curl -X POST https://sandbox.api.thepennyinc.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Authenticate API requests

Send the access token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

The same access token works with Penny Banking, Penny Issuing, and (in Sandbox) Penny Simulation.

# Penny Banking
curl https://sandbox.api.thepennyinc.com/businesses/profile \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
# Penny Issuing
curl https://issuing.sandbox.api.thepennyinc.com/cards/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

You do not need a separate token for each API.

Authentication vs permissions

Authentication verifies which application is calling Penny. Authorization determines what that application is allowed to do.

Penny uses role-based access control (RBAC). Applications can be granted only the permissions they need, and each API operation documents its required permissions.

For example, an application can be allowed to read accounts without being allowed to create accounts or issue cards.

A request can therefore fail even when the access token itself is valid:

See Access Control to configure roles and permissions.

Token lifetime

Access tokens are valid for 24 hours.

Cache and reuse the token rather than requesting a new one for every API request.

Request another token when the existing token expires or Penny returns 401 Unauthorized.

A 403 Forbidden normally indicates a permissions issue and should not be handled by repeatedly requesting a new token.

Keep application credentials secure

Client credentials are server-side secrets.

Never expose a client secret in browser or mobile code, source control, logs, or public configuration.

Store credentials using your platform’s secrets-management system and rotate them if exposure is suspected.

See Access Control for credential management and rotation.