OAuth Method
The Authentication API provides the acquisition/deletion function of access to Resources.
OAuth is used to make a request for authentication of an app.
|
GET |
https://{Request URI Host}/v1/oauth?app_id=[value]&redirect_url=[value]&response_type=[value]&scope=[value]&state=[value] |
|---|
Input Variables
| Required | Parameter | Definition |
|---|---|---|
| ● | app_id | Specify the App ID issued at the time of app registration. |
| ● | redirect_url | Specify the Redirect URL issued when the app was registered. When response_type is specified with code_direct, there is no need to specify the redirect_url. |
| ● | response_type | Specify the type of authentication. The following values can be specified. To access Resources, Granting Access to Company DB must be granted in advance by using code. code: Perform authentication using code. For an app using a Web browser, use this authentication method. |
| ※ | scope | This is required when specifying response_type with “code” or “remove.” Specify the type of Resource to which access is granted or from which access is removed. For the type of the scope that can be specified, see Scope List described later, and for the scope necessary for each Resource, see API List or each Resource API page. When specifying multiple types, delimit them with a comma. When specifying response_type with code_direct, do not specify any scope. |
| state | When specifying response_type with “code” or “remove,” a desired parameter can be specified. When the address is redirected to the URL specified by a redirect_url, the value specified for “state” can also be used. |
Result Values
When the processing is successful, the value of the “code” can be acquired. Use the Token API to acquire an Access Token based on the acquired code.
If an error occurs, the value of the Error is returned. For details, see Authentication and Authorization Error.
Expiration of Code
The Code expires 30 seconds after issuance. Issue a Request for an Access Token within 30 seconds.
Process & Output Values
The Process and Output differ depending on the value specified for response_type.
For details on the Process, see Steps for Authentication.
The following shows an example when redirect_url = http://myapplication.com:
| response_type | Output format | Output example |
|---|---|---|
| code | Add “code” or “Error” to the parameter. |
http://myapplication.com?response_type=code&code=aaa |
| code_direct | The code is returned in the XML format to the Response Body. | <Authentication> <Code>aaa</Code> <Error>0</Error> <Message>Success</Message> </Authentication> |
| remove | Add the processing result to the parameter Deleted successfully: remove_confirmation=0 Deletion failed or canceled: remove_confirmation=-1 |
http://myapplication.com?response_type=remove&remove_confirmation=0 |
Granting Access to Company DB
For an app to access a Resource of HRBC, the app must first be granted access to the Company DB that is to be accessed .
When developing a user app, this granting operation must be performed in the early stages of the development.
When granting access to the Company DB, call the API directly from the Web browser (response_type=code), and log in to the system with the HRBC user ID and then approve the granting of the access privilege.
If this procedure is not performed or there is no necessary access privilege, an error occurs when a request for access to the Resource is made.
[Preparation]
Always start with the status where you are not logged in to HRBC.
To check the login status, access https://hrbc-jp.porterscloud.com on a Web browser.
If a screen other than the login screen is displayed, you are logged in to HRBC, so log out of the system.
[Request example]
The following example grants the privilege of candidate_r and user_r when App ID =ABC and Redirect URL =http://myapplication.com.
Fill the address bar of the Web browser with the following URL to access the page.
https://{Request URI Host}/v1/oauth?response_type=code&app_id=ABC&scope=candidate_r,user_r&redirect_url=http://myapplication.com
On the displayed login screen, enter a company ID, user ID, and password.
When you have successfully logged in to HRBC, the confirmation screen of the granting of privileges appears. Click on [Approve].
When the processing is successfully completed, add code to the parameter for all the apps.
For details on the authentication procedure, see Steps for Authentication.
Scope List
In the OAuth API, one or more scopes among the following can be specified.
| Scope | Description |
|---|---|
| partition_r | Privilege to read Partition information |
| user_r | Privilege to read User information |
| field_r | Privilege to read Field information |
| option_r | Privilege to read Option items |
| client_r | Privilege to read Client |
| client_w | Privilege to write Client |
| recruiter_r | Privilege to read Recruiter |
| recruiter_w | Privilege to write Recruiter |
| contact_r | Privilege to read Contact |
| contact_w | Privilege to write Contact |
| job_r | Privilege to read JOB |
| job_w | Privilege to write JOB |
| candidate_r | Privilege to read Person |
| candidate_w | Privilege to write Person |
| resume_r | Privilege to read Resume |
| resume_w | Privilege to write Resume |
| process_r | Privilege to read Process |
| process_w | Privilege to write Process |
| activity_r | Privilege to read Activity |
| activity_w | Privilege to write Activity |
| contract_r | Privilege to read Contract |
| contract_w | Privilege to write Contract |
| sales_r | Privilege to read Sales |
| sales_w | Privilege to write Sales |
| phase_r | Privilege to read Phase |
| phase_w | Privilege to write Phase |
| attachment_r | Privilege to read Attachment |
| attachment_w | Privilege to write Attachment |