Scope

This documentation is intended for OrangeHRM Professional and Enterprise versions. OrangeHRM Open Source will not be supported by these APIs

User Guide

Step 1- Register the client: OAuth client can be registered by System Admin users by accessing the OAuth Clients tab (Admin -> Configuration -> Authentication -> OAuth Clients). OrangeHRM support two main OAuth Grant Types (Password - mainly for 3rd party user applications, Client Credentials - for data integrations/inter-system communications). It is possible to specify the Client Id and Grant Type when registering an OAuth Client. Secure Client Secret is auto-generated. Upon saving OAuth client scope will be set to "Public" automatically. These details(Client Id/ Client Secrete) need to be stored securely. These details will help to authenticate, and securing the communication with a random token(The Grant Type or regenerated Client Secret can be altered by editing a client).

Step 2 - Request an access token to communicate: Every time the user needs to call the web services, the communication needs to be protected with tokens. To use a web service client needs to request a token by passing the relevant parameters for the grant type(For Password grant type, use 'password' as the grant type and for Client Credentials grant type, use 'client_credentials').

See the example parameters below for password and client credential grant types respectively:
- Parameters (password):
  - client_id: client ID
  - grant_type: password
  - username: username
  - password: password
- Parameters (client credentials):
  - grant_type: client_credentials
  - client_id: client ID
  - client_secret: client secret key
Important-: You have can send the above request parameters as 'form-data', 'json' or 'x-www-form-urlencoded'.

After providing the necessary information for the parameters of the relevant grant type, you have to send a 'POST' request to the token issuing endpoint. The URL for this would be:
- https://:ohrmInstance/oauth/issueToken
You can request an access token from this document's Authentication->Access Token section by sending the sample request. Then you can use that response's access token and use it in other sample request headers.

You can use the following sandbox instance to try-out APIs.

Step 3 - Call the web service: Calling the web service involves making an HTTP request to a specific URL, passing any post parameters, and adding the access token to the header of the call.
Basically what you have to do is as follows.
- Provide the URL with the relevant HTTP method. (If the HTTP method is POST, DELETE or UPDATE you have to provide the necessary request body parameters as well).
- Then in the headers, you have to provide the 'Authorization' header and for the value, you should give it as 'Bearer {access token}'.
  (i.e-: Authorization: Bearer {access token})
API Version Disclaimer-: You can send the 'Accept' header with a version to get results based on a specific version of the API that you are requesting.
(i.e-: Accept: json,text;version=1). If you do not mention the specific API version, the response will be returned based on the latest API version. We recommend you use a specific version of the API, if you do not need the latest changes in order to be compatible with OrangeHRM for a longer period.

Step 4 - Getting the response: Once a web service is successfully called it will return a response containing any errors/warnings or success messages. If the call is a success, the web service will return the requested details or warnings/errors if it's a 'GET' method call. If it's any other method, any defined success message or warnings/errors defined in each method will be returned.
Warning example - 400: Unsupported resource request - Accepted types are 1 and 2
Success example - 201: Successfully saved

The response returned by the API are in raw format so any further processing or escaping needs to be done at the consumer application
The default date format supported is 'YYYY-MM-DD' (Ex:- '2012-12-12').