HReasily Connect · API guide
Authenticate with the HReasily Pro API (OAuth 2.0)
Overview
The HReasily Pro API uses the OAuth 2.0 Authorization Code flow. Your application sends an admin to HReasily Pro to approve access, receives a short-lived authorisation code, and exchanges it for an access token. Every API request then carries that token.
The token exchange uses your client secret, so it must run on a secure backend server, never in a browser or mobile app.
Key URLs
| What | URL |
|---|---|
| Manage your applications | https://developers.pro.hreasilygroup.com/applications/ |
| Authorisation endpoint | https://api.pro.hreasilygroup.com/oauth/authorize/ |
| Token endpoint | https://api.pro.hreasilygroup.com/oauth/token/ |
| API base URL | https://api.pro.hreasilygroup.com/ |
Step 1Create an OAuth application
- Go to Applications and sign in.
- Create a new application and add your Redirect Uris. The redirect URI you use later must match one of these exactly.
- Copy the Client id and Client secret. The secret is shown only once. Store it in a secure place, such as a secrets manager.
Lost the secret? Open the application and click Regenerate secret. The old secret stops working.
Step 2Send the user to the authorisation endpoint
Redirect the HReasily Pro admin to:
GET https://api.pro.hreasilygroup.com/oauth/authorize/
?client_id=YOUR_CLIENT_ID
&response_type=code
&redirect_uri=YOUR_REDIRECT_URI
&state=RANDOM_STRING| Parameter | Description |
|---|---|
client_id | Required. Your application's Client id. |
response_type | Required. Must be code. |
redirect_uri | Required. Must exactly match one of your registered Redirect Uris. |
state | Recommended. A random value you check on return, to protect against cross-site request forgery. |
code_challenge, code_challenge_method | Optional for server-side apps, required for public apps. See Use PKCE with the HReasily Pro API. |
Step 3Receive the authorisation code
The admin signs in to HReasily Pro and approves access. HReasily Pro then redirects to your redirect_uri:
https://your-app.example.com/callback/?code=AUTHORISATION_CODE&state=RANDOM_STRINGCheck that state matches what you sent. If the admin denies access, the redirect contains an error parameter instead.
Step 4Exchange the code for tokens
From your server, call the token endpoint with a Basic Authorization header containing your base64-encoded client_id:client_secret:
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_URIExample response:
{
"access_token": "...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "..."
}Step 5Call the API
Send the access token in the Authorization header of every request. All requests must use HTTPS.
curl -H "Authorization: Bearer ACCESS_TOKEN" \
https://api.pro.hreasilygroup.com/core/employees/Step 6Refresh the access token
When the access token expires (see expires_in, in seconds), use the refresh token to get a new one without asking the admin again:
curl -X POST https://api.pro.hreasilygroup.com/oauth/token/ \
-H "Authorization: Basic BASE64(CLIENT_ID:CLIENT_SECRET)" \
-d grant_type=refresh_token \
-d refresh_token=REFRESH_TOKENAPI basics
- Format: requests and responses are JSON, UTF-8.
- Dates: ISO 8601 in UTC, for example
2026-11-16T09:30:00Z. - Pagination: list endpoints use the
pagequery parameter (starting at 1, default page size 10). Responses includecount,nextandprevious. - Errors: 4xx means a problem with the request, 5xx a problem on our side. Error responses are JSON, for example
{"error": "invalid_request", "error_description": "..."}.
Troubleshooting
| Problem | What to check |
|---|---|
| Redirect URI error on the authorisation page | The redirect_uri must match a registered Redirect Uri exactly, including the trailing slash. |
invalid_client at the token step | The client secret is wrong or was regenerated. Regenerate it in Applications and update your app. |
invalid_grant at the token step | The code was already used or has expired, or redirect_uri differs from Step 2. Start the flow again. |
| 401 on API calls | The access token has expired. Refresh it (Step 6). |
Need help?
Contact our support team at connect@hreasilygroup.com. Include your application name (never your secret or tokens) and the error you see.
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