Skip to main content

Before your application can call Wych Recipient APIs, it must prepare the required access credentials.

Each API call uses two access headers:

  • x-api-key
  • authorisation

The API key is retrieved from your application configuration in the Wych portal. The bearer token is retrieved from the OpenID token endpoint using your client credentials.

AU CDRNZ PNZ

Before you start​

Before preparing access credentials, make sure you have:

  • a registered application in the Wych portal
  • access to the application configuration record
  • your issued client ID
  • your issued client secret
  • your issued API key
  • the correct environment base URLs for sandbox or production

What you will use​

To call the Wych API, your application sends:

  • x-api-key on every request
  • authorisation: bearer <TOKEN> on protected requests

The API key identifies your application for access management, throttling and traffic tracking. The bearer token proves that your application has authenticated successfully using its client credentials.

API key​

Your API key is issued as part of your application configuration.

Include it on every request:

x-api-key: your_api_key

Treat the API key as sensitive configuration. It should be stored securely and not exposed in client-side code, public repositories or unsecured logs.

Discover the token endpoint​

Before requesting a bearer token, retrieve the OpenID configuration document for your environment and identify the token_endpoint.

curl --location 'https://login.wych.app/realms/partner/.well-known/openid-configuration'

You should expect a response containing values such as:

  • issuer
  • authorization_endpoint
  • token_endpoint
  • jwks_uri

Use the token_endpoint value from that response for the next step.

Retrieve a bearer token​

Exchange your client credentials for an access token using the token endpoint.

curl --location '{{token_endpoint}}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=client_123456789' \
  --data-urlencode 'client_secret=supxxxxxxxxret' \
  --data-urlencode 'grant_type=client_credentials'

A successful response will typically include:

  • access_token
  • expires_in
  • token_type
  • scope
{
    "access_token": "eyJ...DcQ",
    "expires_in":   900,
    "token_type":   "Bearer",
    "scope":        "email EXECUTE:TOKEN_EXCHANGE READ:APP_USERS profile READ:APP"
}

Use the token on API requests​

Once the token has been issued, include it in the authorisation header.

authorisation: bearer <TOKEN>

An authenticated API request will therefore look like:

curl --location 'https://api.wych.example/resource' \
  --header 'x-api-key: your_api_key' \
  --header 'authorisation: bearer your_access_token'

Token management guidance​

Cache the bearer token and refresh it only when needed.

Use the returned expires_in value to determine when the token should be renewed. Avoid requesting a new token for every API call unless that is genuinely required by your implementation.

In production, you should also:

Always:
  • store client credentials securely
  • redact secrets and tokens from logs
  • handle token expiry and retry logic cleanly
Never:
  • expose tokens in browser code

What this step enables​

Once your application can successfully retrieve a bearer token and send both required headers, you are ready to begin the consent journey.

Next step​

Continue to Consent hosted to launch a Wych-hosted consent flow and connect a customer account.