OpenID Connect Login API

Overview

HTTP Method: Post
Path: /api/gateway.php/{company}/v1/oidcLogin
Headers: Content-Type- application/x-www.form.urlencoded
Accept- Optional- To request a JSON formatted response, send “application/json”

Login with an Application Key and a BambooHR user’s ID Token:

POST Variables:

  • id_token – The ID Token for an authenticated user provided by BambooHR. See here.
  • applicationKey – The application key provided to you by BambooHR.

Response:
On success, an HTTP 200 response code and a JSON or XML object will be returned. The response object includes the API key to use when making requests for this user and the user’s ID. If the user is currently associated with an employee, then the employee ID is returned as well. If not, then the tag will be omitted. On failure, an HTTP response in the range of 400-599 and a small snippet of XML indicating failure will be returned.

Note: The association of users to employees is under the control of the account administrator. The employee ID may change if the administrator updates the user.

Sample request (with HTTP headers):
POST /api/gateway.php/testcorp/v1/oidcLogin
Host: api.bamboohr.com
Content-Type: application/x-www-form-urlencoded

applicationKey=1d55bf6891bd5ef3c285a3a9075748856db1c196
&id_token=1234

Sample successful response (HTTP response code=200):

{
"success":true,
"userId":1,
"employeeId":25,
"key":"e254c96d97a12dc561f56d8713e58ac6c2a8c166"
}
<auth>
<response>authenticated</response>
<userId>1</userId>
<employeeId>25</employeeId>
<key>e254c96d97a12dc561f56d8713e58ac6c2a8c166</key>
</auth>

Sample failed response:

{
"success":false,
}
<auth>
<response>declined</response>
</auth>

HTTP Status Codes

Every request includes an HTTP status code with the result. The status code should be examined before the response.

Successful status codes (2xx)
200 OK – The request was successful.
Client error status codes (4xx)
400 Bad Request – The request was invalid or could not be understood by the server. Resubmitting the request will likely result in the same error.
412 Invalid or Expired token – This indicates the token has expired (or was invalid). Token’s expire after an hour.
You can future proof your code by using the following ranges:
200–299 as success
400–499 as client request errors
500–599 as server errors