Authenticate with the HReasily Pro API (OAuth 2.0)

Modified on Mon, 16 Nov at 11:18 PM

HReasily Connect · API guide

Authenticate with the HReasily Pro API (OAuth 2.0)

Applies to HReasily Pro API Updated 16 November 2026

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

WhatURL
Manage your applicationshttps://developers.pro.hreasilygroup.com/applications/
Authorisation endpointhttps://api.pro.hreasilygroup.com/oauth/authorize/
Token endpointhttps://api.pro.hreasilygroup.com/oauth/token/
API base URLhttps://api.pro.hreasilygroup.com/

Step 1Create an OAuth application

  1. Go to Applications and sign in.
  2. Create a new application and add your Redirect Uris. The redirect URI you use later must match one of these exactly.
  3. 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
ParameterDescription
client_idRequired. Your application's Client id.
response_typeRequired. Must be code.
redirect_uriRequired. Must exactly match one of your registered Redirect Uris.
stateRecommended. A random value you check on return, to protect against cross-site request forgery.
code_challenge, code_challenge_methodOptional 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_STRING

Check 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_URI

Example 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_TOKEN

API 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 page query parameter (starting at 1, default page size 10). Responses include count, next and previous.
  • 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

ProblemWhat to check
Redirect URI error on the authorisation pageThe redirect_uri must match a registered Redirect Uri exactly, including the trailing slash.
invalid_client at the token stepThe client secret is wrong or was regenerated. Regenerate it in Applications and update your app.
invalid_grant at the token stepThe code was already used or has expired, or redirect_uri differs from Step 2. Start the flow again.
401 on API callsThe 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

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