HReasily Connect · API guide
Use PKCE with the HReasily Pro API
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 application | PKCE |
|---|---|
| Confidential client: runs on a server and keeps a client secret | Optional, recommended |
| Public client: mobile, desktop or single-page app that can't keep a secret safe | Required |
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=S2563. 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_VERIFIERHReasily 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_challengein step 2, you must sendcode_verifierin 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
Feedback sent
We appreciate your effort and will try to fix the article