OAuth authorization for the Bullhorn REST API

Bullhorn uses OAuth 2.0 as the authorization mechanism for the Bullhorn REST API. OAuth provides a secure way for customers to use applications that make Bullhorn REST API calls.

OAuth 2 participants

The OAuth 2 process involves the following participants:

  • Resource owner

    The Bullhorn user who wishes to use a partner’s application by granting it access to his or her Bullhorn data.

  • OAuth 2 client

    The Partner’s application.

  • OAuth 2 server

    The Bullhorn OAuth 2 server.

OAuth 2 client registration

To participate in OAuth, partners must register with Bullhorn. The most important pieces of data in the
registration are:

  • Client Id, which is a unique identification string assigned to each partner
  • Client secret, which is the client password

General OAuth 2 workflow

The ultimate goal of the OAuth 2 process is to obtain a valid access token, which can in turn be used to
gain access to Bullhorn’s REST services.

An OAuth API key can be configured to return long-lived refresh tokens in addition to access tokens. The OAuth 2 client must obtain the very first access token and refresh token by using an authorization code. However, for subsequent requests the client can provide the latest refresh token to get a new access token (and refresh token). The client can use the new access token to gain access to the REST services. This allows the client to avoid getting a new authorization code for every new REST API session. A refresh token expires after it is used once to successfully obtain a new access token and refresh token.

The typical parts of the OAuth process are:

  1. Obtain an authorization code.
  2. Use the authorization code to obtain an access token and a long-lived refresh token.
  3. Use the last issued refresh token to obtain a new access token and refresh token.

Before using OAuth, partners must complete the OAuth registration process to obtain an OAuth API key (client ID) from Bullhorn.

Bullhorn OAuth uses the following high-level workflow. Partners can handle this process programmatically or manually in a browser depending on the nature of their applications.

  1. An OAuth 2 client makes an authorization request to the Bullhorn server. The client provide a clientId and other identifying information.
  2. The Bullhorn OAuth 2 server requires a valid user login.
  3. The OAuth 2 client provides a valid user login.
  4. The Bullhorn OAuth 2 server prompts the client to accept or decline a terms of service agreement. The terms of service agreement is only displayed the first time a user’s credentials are provided for the specified clientId.
  5. If the OAuth 2 client has accepted the terms of service agreement, the Bullhorn OAuth 2 server grants authorization and redirects the request to a redirect URI provided in the OAuth key. An authorization code is provided on the end of the redirect URI.
  6. The OAuth 2 client requests an access token. The request includes the authorization code and other identifying information.
  7. If the Bullhorn OAuth 2 server accepts the request, it provides the client with an access token.
  8. The OAuth 2 client uses the access token in a REST login request to get a REST API session key and establish a REST API session.

See Getting Started with the Bullhorn REST API for information about the specific calls a client must make in the OAuth process.

OAuth 2 clients

OAuth 2 clients can be categorized into two major types:

  • Clients with user agents; for example, a web application, iPhone application, or Android application where there is a human user present
  • Clients without user agents; for example, a cron job where no human user is involved

OAuth 2 clients with user agents

For this type of client, the normal OAuth 2 process is followed. The human user is present to log in
and grant access when necessary. However, this does not preclude clients from storing and using refresh tokens to minimize the impact of OAuth 2 logins.

A special sub-class of this type of client is a custom application that uses the REST API within the Bullhorn staffing application. Such applications are typically presented to the user within an iframe. You can add a custom menu action or tab to the Bullhorn staffing application for the custom iframe application. The process is the same as it is for applications that do not use the REST API, as described in Application Extensibility.

Users must log into OAuth before using the custom iframe application, but a session cookie named OAUTHSESSION ensures that users only have to log into OAuth once per session. The redirect URI(s) that you provide to Bullhorn for your OAuth API key should include the URI you intend to use for the custom application. The redirect URI determines the page that displays when a user successfully logs in via OAuth.

OAuth 2 clients without user agents

For this type of client, the process of obtaining an authorization code cannot be performed during the normal operation of the client because no person is available to log in and grant access. However it is possible for the client to perform this part of the process outside the normal operating scope and store the refresh token, which can be used to obtain access tokens during the normal operation of the client.

One example is an external application, such as a custom career portal, that integrates with Bullhorn but users of the application are not users of Bullhorn. In this case, a candidate applying for a job on the custom career portal is the user of the external application, but is not a Bullhorn user. The external application can programmatically perform the OAuth steps to obtain the authorization code and the initial access token and refresh token. Optionally, the partner can go through the full browser-based process that includes manually entering credentials in the OAuth login page to obtain the authorization code and the initial access token and refresh token. The client can then use the refresh token to obtain additional access tokens and refresh tokens as needed during normal operation.

Another example is an external application, such as a Bullhorn Marketplace application, that integrates with Bullhorn where the users of the external application are also Bullhorn users. In this scenario, the external application could programmatically perform the OAuth steps to obtain the authorization code and the initial access token and refresh token. Optionally, the partner could include something like the following text as part of the signup process for the application:

“The next step redirects you to Bullhorn’s authorization server. Please log in and accept the terms of service. You will
then be returned here.”

The client can then use the refresh token to obtain additional access tokens and refresh tokens as needed during normal operation.

In all cases, the partner must provide a means to get a new refresh token to account for situations where a refresh token encounters an unrecoverable error. The resource owner may be notified of the failure by email, sms, or another means to inform them go through the full authorization process to obtain a new refresh token.

See the Bullhorn Style Guide for user interface design guidelines.

More information about OAuth 2.0