API v3

The API v3 functionality is available in the “PRO” pricing plans.

To upgrade your plan, you can contact your personal manager or email us at support@hurma.work.

Creating an API application

1. Go to the “Settings” – “For developers” page in HURMA.

   

2. Click the “Add API Client” button. In the form that opens, fill in the following fields:

• Title – any name for your application (e.g., "ERP Integration").

• Authorization Type

  • Authorization code – recommended for external applications with user authorization (via OAuth 2.0).

  • Password – direct exchange of login and password for a token (used in trusted integrations, e.g., backend-to-backend).

• Redirect – the address where the system will send the authorization code after the user logs in. This is a required field when using the “Authorization code” type.

• Description – additional information or purpose of the integration (optional).

• API Access Settings and Sensitive API Fields – a set of permissions that will be available to this application.

3. Click “Save” – after that, the application will appear in the list of generated clients. You will then receive the following data:

• Client ID

• Client Secret

These values will be required for authorization.

Authorization via OAuth 2.0

Integration with the HURMA API is possible using two methods:

Type 1: Authorization Code (recommended)

This method is suitable if the integration involves user authorization through a user interface.

1. Generate an authorization request:

GET https://yourcompany.hurma.work/api/v3/oauth/authorize
?response_type=code
&client_id=YOUR_CLIENT_ID
&redirect_uri=YOUR_REDIRECT_URI

2. user authorizes → HURMA will redirect to your redirect_uri with a code in the URL parameters (?code=XXXXXX).

3. Exchange the code for an access token.

POST https://yourcompany.hurma.work/api/v3/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&code=CODE_FROM_STEP_2
&redirect_uri=YOUR_REDIRECT_URI

4. Receive the access token in the response.

Type 2: Password

This method is suitable for server-side scenarios without user interaction.

Send a request for a token:

POST https://yourcompany.hurma.work/api/v3/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=password
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&username=USER_EMAIL
&password=USER_PASSWORD

Using the token

You can view all available endpoints, request structures, and responses in Swagger.

Add the obtained access_token to every API request:

GET /api/v3/users
Host: yourcompany.hurma.work
Authorization: Bearer YOUR_ACCESS_TOKEN

Security tips

• Use HTTPS for all requests.

• Store your Client Secret in a secure location.

• Do not use Password Flow in a browser.

• Regularly update your access token using the refresh_token if the "Authorization Code" authorization type is used.

Support

If you have any questions, you can contact our team:

• via the in-system chat

• by email at support@hurma.work

• on Telegram