Hubpay API authentication

Hubpay integrations can involve API authentication, enterprise SSO and customer-approved account linking. They solve different problems.

Requirement	Model	Purpose
Your backend calls Hubpay	Client credentials and bearer token	Authenticates a server-to-server API request
A user moves between enterprise applications without another login	SSO using an agreed OIDC or SAML setup	Authenticates the user
A customer gives a third-party app access to their Hubpay account	App connection request and scoped approval	Authorises account access and actions

API authentication

Hubpay issues a clientId and clientSecret during partner or customer onboarding. Exchange these credentials for a short-lived bearer token, then include that token in the Authorization header of API requests.

Obtain a bearer token

curl -X POST https://api.hubpay.io/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET"
  }'

The response contains the access token and its lifetime:

{
  "access_token": "eyJraWQiOiJ...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Call the API

curl -i -X GET \
  'https://api.hubpay.io/v1/webhooks' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Try an API request from these docs

The interactive API reference can authenticate sandbox requests for you:

1. Open Generate JWT access token.
2. Select the Sandbox server, enter your sandbox clientId and clientSecret, then choose Send API request.
3. After the token request succeeds, open another endpoint and choose Send API request. The access token is reused for the current browser tab.
4. Supply AccountId as well on endpoints that require account context.

Use dedicated sandbox credentials in the browser-based explorer. Keep production credentials and all credentials used by your real integration in a server-side secret store.

• Keep client credentials in a server-side secret store
• Never include a client secret in browser, mobile or distributed package code
• Request a new token when the current token expires
• Use a separate credential set for each environment and integration

Account context

Some API operations also require an AccountId header. This selects the Hubpay account the authenticated integration is operating on; it does not replace the bearer token.

For a connected app, only use the customerAccountId returned by an active, customer-approved connection. See App connections.

Enterprise SSO

SSO is a user-login concern and is separate from Hubpay API authentication. If users need to move from an enterprise platform such as Salesforce into Hubpay without another login, agree the tenant, identity provider, claims and federation protocol with Hubpay before implementation.

Use established terms in solution designs:

• OpenID Connect (OIDC) for identity on top of OAuth 2.0
• SAML 2.0 for enterprise identity federation
• Client credentials for server-to-server API access
• Account linking for a customer's scoped app connection

Do not use “SSO” to describe a bearer token or an app connection approval.