Skip to content
Last updated

API authentication

Your backend needs issuer access to send customer and purchase data and read reward results. Percents provisions your API credential and provides it securely. Use the source-IP, header and environment guidance below to connect cashback and branded requests while keeping the secret on your server.

Network access and tokens

Provide Percents with the source IP addresses or CIDR ranges of your sandbox and production backend callers. Update the approved addresses when your egress changes. Requests from other addresses can fail before token authentication.

Send this header on issuer API requests:

Authorization: token <tok_id>:<api_secret>

For example:

curl --fail-with-body 'https://sandbox.percents.com/api/v2/offers?page=1&pageSize=25'   -H 'Authorization: token tok_11111111-1111-4111-8111-111111111111:api_test_secret'

A token identifies the issuer. Supplying another issuer's customer, offer or external event ID does not grant access to that issuer. Ownership checks apply to both public IDs and external-ID lookup. A syntactically valid identifier does not confer access.

Store and rotate secrets according to your institution's credential controls. Do not expose issuer tokens in client applications, iframe messages, URLs or logs.

PrefixMeaning
tok_Identifies a token.
api_Can identify a credential-management resource. It is not the secret itself.

Optional SDK sessions

The optional branded SDK uses a separate, short-lived customer session issued through the issuer server. Server-to-server cashback calls do not require this signed session setup. See SDK authentication.

Failures

A missing or invalid credential returns an authentication failure. Insufficient access can return an authorization failure. See the error guide for public response fields and retry guidance. Keep the returned uuid for support and do not parse the human-readable message.