Use PKCE with the HReasily Pro API

Modified on Mon, 16 Nov at 11:18 PM

HReasily Connect · API guide

Use PKCE with the HReasily Pro API

Applies to HReasily Pro API (OAuth 2.0 Authorization Code flow) Updated 16 November 2026

What is PKCE?

PKCE (Proof Key for Code Exchange, pronounced "pixie") adds a one-time secret to the Authorization Code flow. Your app creates a random value before it sends the user to log in, and proves it still has that value when it exchanges the code for tokens. If someone intercepts the authorisation code, they can't use it without that value.

Do I need it?

Your applicationPKCE
Confidential client: runs on a server and keeps a client secretOptional, recommended
Public client: mobile, desktop or single-page app that can't keep a secret safeRequired

All applications registered today are confidential clients. Adding PKCE is still good practice, because it protects against stolen authorisation codes at no extra cost.

How to add PKCE

1. Create a code verifier and code challenge

Before each authorisation request:

  • Code verifier: a cryptographically random string of 43 to 128 characters, using letters, digits and - . _ ~. Generate a new one every time.
  • Code challenge: the SHA-256 hash of the verifier, base64url-encoded without padding.

Example (Python):

import base64, hashlib, secrets

code_verifier = secrets.token_urlsafe(64)[:128]
digest = hashlib.sha256(code_verifier.encode()).digest()
code_challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()

Store the verifier in the user's session. Send only the challenge.

2. Add the challenge to the authorisation request

GET https://api.pro.hreasilygroup.com/oauth/authorize/
  ?client_id=YOUR_CLIENT_ID
  &response_type=code
  &redirect_uri=YOUR_REDIRECT_URI
  &state=RANDOM_STRING
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256

3. Send the verifier with the token request

curl -X POST https://api.pro.hreasilygroup.com/oauth/token/ \
  -H "Authorization: Basic BASE64(CLIENT_ID:CLIENT_SECRET)" \
  -d grant_type=authorization_code \
  -d code=AUTHORISATION_CODE \
  -d redirect_uri=YOUR_REDIRECT_URI \
  -d code_verifier=CODE_VERIFIER

HReasily Pro hashes the verifier and checks it matches the challenge from step 2. If it doesn't, the token request fails with invalid_grant.

Common mistakes

  • Reusing a verifier. Create a new verifier for every authorisation request.
  • Standard base64 instead of base64url. The challenge must use - and _, with no = padding.
  • Sending a challenge but no verifier. If you send code_challenge in step 2, you must send code_verifier in step 3.

Related articles

Need help?

Contact our support team at connect@hreasilygroup.com.

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article