Skip to content
English - Australia
More support
visit impos.com.au
  • There are no suggestions because the search field is empty.

Provision and diagnose partner access

Provision and diagnose OAuth access without exposing secrets. Use this article to provision partner API access and to work out why a partner is getting 401 or 403 responses. Never ask for, paste or test a client secret or raw token in chat, email or a ticket.

How access works

Partner API access has two layers:

  1. Authentication. Keycloak authenticates the client and issues a token for the intended service.
  2. Authorisation. Impos resolves the client or user and checks its permission at the requested hierarchy scope.

A valid token can therefore still receive 403, and a successful token request does not prove that sites are provisioned.

Response

What it means

Where to look

401 Unauthorized

The token or client could not be authenticated for this service.

Token, realm, audience, client status, secret

403 Forbidden

Authentication worked; the caller lacks permission for this action or scope.

Role, permission, hierarchy level, environment

403 on /v1/sites

No accessible sites were found for the caller.

Grants and hierarchy placement

 Provision access

Work through this checklist before closing the request:

  • Confirm whether the request is for UAT or production. Never reuse credentials across environments.
  • Confirm the intended service audience: core API or Loyalty.
  • Confirm the partner client identity and the owning partner record, where applicable.
  • Grant the least hierarchy scope required: management group, organisation, or site.
  • Grant only the permissions needed for the documented partner use case.
  • Test token acquisition, then call GET /v1/sites or the sentinel endpoint for the intended service.
  • Record the client ID, grant scope, environment, owner, issue date and rotation contact in the support record. Never record the secret.
  • Require working UAT evidence before issuing production access.


    Diagnose 401 Unauthorized

    Check these in order:

    1. The request contains Authorization: Bearer <token>.
    2. The token is unexpired and was issued by the realm that matches the environment.
    3. The token audience includes the requested service.
    4. The client is enabled and the supplied secret is current.
    5. The token request used application/x-www-form-urlencoded with grant_type=client_credentials.
    6. For Loyalty, the requested token includes the loyalty scope.

    If you need more detail, ask the partner for the decoded, non-sensitive claims rather than the raw token. Claims can still contain identifiers, so keep them within the ticket's access controls.

    Diagnose 403 Forbidden

    Authentication succeeded, so the problem is authorisation. Verify:

    • the permission required by the exact method and route;
    • the caller's assigned role;
    • the role's hierarchy level;
    • that the requested organisation or site sits under that grant; and
    • that the grant exists in the same environment as the request.

    Permissions cascade downward, not upward. A site grant does not confer organisation-wide access.

    Diagnose site discovery returning 403

    When /v1/sites finds no accessible sites, it currently returns 403 rather than an empty list.

    1. Inspect the client's grants.
    2. Confirm that the granted resource exists, is active, and contains the expected sites.
    3. Compare the client's organisation access with the intended site hierarchy.
    4. Correct either the grant or the hierarchy placement.
    Rotate a suspected exposed secret

    If a secret may have been exposed:

    1. Do not test it in chat or email.
    2. Rotate it through the authorised process.
    3. Send the replacement through the approved secret channel.
    4. Record the rotation event in the support record, without the value.
    5. Confirm the old credential no longer works.