Guide

1. Guide Users to Authorize Your App

Guide users to the following URL:

GET https://server.workstem.com/auth/oauth/authorize?response_type=code&client_id=CLIENTID&scope=SCOPE1,SCOPE2&state=SddHh4j896=&redirect_uri=http://localhost/index

Parameter Descriptions:

• response_type=code
• client_id: The client_id generated by WorkStem when creating the app.
• scope: The set of permissions required by the app.
• redirect_uri: The app page to which the user will be redirected after authorization is completed. It must be registered in WorkStem before use.
• state: A random string that will be returned to the app after authorization is completed, used to prevent counterfeit attacks.

2. User Authorization

After user authorization is completed, the user will be redirected to the redirect_uri provided in step one, with two additional request parameters:

• code: A one-time code used to exchange a token, which will automatically expire if not used within 5 minutes.
• state: The state provided in the first step. If the returned state does not match the one you provided, it may be subject to a counterfeit attack, and you should interrupt this request.

If an exception occurs during user authorization or if the user refuses authorization, WorkStem will redirect to the redirect_uri with an additional error parameter.

3. Exchange Token with Code

Once you have the code, you can exchange it for a token.

You need to send the following request to obtain a token.

Request

• URL：https://server.workstem.com/auth/oauth/token
• Method：POST
• Content-Type：multipart/form-data

Parameters

name	required	description
grant_type	true	authorization_code
code	true	The code obtained after user authorization.
client_id	true	Consistent with the client_id in the first step.
client_secret	true	The client_secret generated by WorkStem for the client_id.
redirect_uri	true	Consistent with the redirect_uri in the first step.

WorkStem will verify all parameters in the third step request to ensure that the code has not expired and that the client_id and client_secret match. If the verification is successful, WorkStem will generate a token and return the following content.

{
  "access_token": "xxxxx",
  "token_type": "bearer",
  "refresh_token": "xxxxx",
  "expires_in": 1799,
  "scope": "openapi",
  "tenant_id": "123456",
  "user_id": "123456789",
  "jti": "6191833f-4f1a-49cf-b84f-2e0177db2688"
}

Parameter Descriptions:

• access_token: Used to request API interfaces, expires after 30 minutes by default.
• token_type: Fixed as bearer.
• refresh_token: After the access_token expires, you can use the refresh_token to get a new access_token. The refresh_token expires after 30 days by default.
• expires_in: The remaining expiration time of the access_token, in seconds.
• scope: The resource permission of the token.
• tenant_id: Tenant ID.
• user_id: User ID, one user may include multiple tenant IDs.

4. Request API Interface with Token

Use the obtained access_token to request API interfaces. Note that there is a space between Bearer and access_token in the request header.

GET https://server.workstem.com/api/v1/test/index
Authorization: Bearer access_token

5. Refresh Token

Access tokens expire after 30 minutes, at which point you need to use the refreshToken to refresh the accessToken. The request format is as follows:

Request

• URL：https://server.workstem.com/auth/oauth/token
• Method：POST
• Content-Type：multipart/form-data

Parameters

name	required	description
grant_type	true	refresh_token
client_id	true	Consistent with the client_id in the first step.
client_secret	true	The client_secret generated by WorkStem for the client_id.
redirect_uri	true	Consistent with the redirect_uri in the first step.
refresh_token	true	The refresh_token returned when the token was exchanged in step three. Note that after refreshing the token, the refresh_token will also be refreshed, and the app needs to update the stored refresh_token according to the returned result.

Refresh Token Response:

{
  "access_token": "xxxxx",
  "token_type": "bearer",
  "refresh_token": "xxxxx",
  "expires_in": 1799,
  "scope": "profile",
  "tenant_id": "123456",
  "user_id": "123456789",
  "jti": "3d3d10c5-f9ec-4446-a1fc-01bb1f6e8fa4"
}

6. Appendix

scope

scope	description
company	Company info
position	Position info
department	Department info
location	Location info
tag	Tag info
cost_center	Cost center info
people	People(All fields)
people_std	People(Standard fields)
attendance	Attendance info
timesheet	Timesheet info
leave	Leave info
payroll	Payroll info