Skip to main content

Authentication (OAuth 2.0)

Set up authentication for your API requests

Overview

Before you start, make sure you have completed the previous guide: Network Access (mTLS & IP)

API requests are authenticated using OAuth 2.0. This ensures that:

  • Each request is securely verified
  • Only authorised systems can access the APIs

Authentication is based on:

  • A JWT signing key pair
  • Credentials issued to your organisation:
    • client_id
    • kid (key ID)

Plan for authentication early

Authentication setup requires coordination and configuration. You should begin this early to avoid delays later.

What typically takes time

  • Generating and managing signing keys
  • Registering keys and completing onboarding
  • Internal security and approval processes

How it works

Authentication uses the OAuth 2.0 client credentials flow with a signed JSON Web Token (JWT). A signed JWT is used to prove the request came from your system and has not been modified.

At a high level:

  1. You generate a JWT signing key pair
  2. You provide your public key
  3. You receive:
    • client_id
    • kid
  4. Your system uses the private key to sign requests for access tokens

Access tokens are then used to call APIs — covered in the next guide: Using Access Tokens.

Step 1

Generate signing keys

Generate an elliptic curve key pair for each environment using the following OpenSSL commands:

openssl ecparam -name prime256v1 -genkey -noout -out private.pem
openssl ec -in private.pem -pubout -out public.pem
Step 2

Provide your public keys

  • Provide a public key for each environment (non-production and production). Only share public keys — never share your private key.
  • Store the private and public keys for later use in a safe and secure place.
  • Your keys must be in standard PEM format:
-----BEGIN PUBLIC KEY-----
Your key
-----END PUBLIC KEY-----
Step 3

Receive your credentials

Once your keys are registered, you will receive a <<kid>> and <<client_id>> for each environment. These are required when requesting access tokens.

The Key ID (kid) can optionally be generated dynamically. Per the JSON Web Key Thumbprint specification (RFC 7638) this is a thumbprint of the required JSON fields from the JSON Web Key (JWK):

base64UrlEncoded( SHA256( '{"crv":"P-256","kty":"EC","x":"...","y":"..."}' ) )

Scopes

Access tokens must include one or more scopes, depending on which APIs you are using. You will specify scopes when requesting a token (see Using Access Tokens).

OAuth API scopes
APIScopes
NameCheckpayments:namecheck:read
PayTopayments:agreements:read payments:agreements:write payments:agreements:amend payments:payments:read payments:payments:write
Fast Paymentspayment-initiation.core-payments.payment-order-initiation.write
FX APIforeign-exchange.partner-quote.read-execute

JWT Key Rotation

Each <<client_id>> can be associated with multiple JWT Public Keys.

To rotate keys:

  1. Generate a new key pair
  2. Provide the new public key
  3. Update your system to use the new private key
  4. Remove the old key when no longer required

Old JWT keys should be removed when they're no longer required.

Common issues

Authentication fails

  • Public key not registered correctly
  • Incorrect kid used

Invalid signature errors

  • JWT signed with wrong private key
  • Mismatch between key and kid

What's next?

Follow the Using Access Tokens guide to continue.