Authentication Information

We require applications to authenticate all of their requests with OAuth 2.0.

Creating an OAuth Application

You may begin by having your administrator create an application from the Settings page. An application requires a name and a callback URL. The callback URL is an endpoint on your application where we will send authentication responses. For initial testing, we provide a way for you to proceed with testing without needing a live application to recieve these responses.

Once the application has been created, your administrator will see an application key and a secret key. You will need both of these values as they are used in all OAuth requests. The administrator may also authorize the application at this time. This process results in an access code (also known as a grant token) that is either sent to your application or automatically converted to an access token (skipping the next step listed below), depending on how the application was configured.

Two Ways to Authenticate

CareerPlug's API offers two grant types for authenticating with the API, client_credentials and authorization_code. The client_credentials grant type is the most straight-forward grant type, while the authorization_code grant type is a more typical user centrict OAuth2 authentication flow.

---

Client Credentials Grant Type

If you are building a custom integration against CareerPlug's API the client_credentials grant type may be a good choice for your authentication strategy.

This grant type works by submitting a request a POST request the /oauth/token endpoint including your CLIENT_ID and CLIENT_SECRET. The result of a successful call is a payload that includes an access_token that expires in 48 hours. There is no refresh token involved, so, when the code expires all you have to do is make the same request as above to receive a new token.

Example Request:
curl -X POST https://app.careerplug.com/oauth/token?grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET

Replacing CLIENT_ID and CLIENT_SECRET with the appropriate values from your newly created application.*
*Please note that your CLIENT_ID is labeled Application, and CLIENT_SECRET is labeled Secret of the credentials page of your API application.

Example Response: (note that access_token has been redacted)
{ "access_token": "*****************", "token_type": "Bearer", "expires_in": 172800, "created_at": 1635956053 }

---

Authorization Code Grant Type

Authorizing your application and receiving an Access Code

After creating your application and receiving your credentials you will need to authorize your application. The user who created the application in CareerPlug will need to visit the following url, note the user must be logged into CareerPlug.

https://app.careerplug.com/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code

Replacing CLIENT_ID and REDIRECT_URI with the appropriate values from your newly created application.

Creating an Access Token

Authorizing an application results in an access code that must be converted to an access token within ten minutes. The access code expires after that time. In order to convert an access code to an access token, perform an http post to https://app.careerplug.com/oauth/token with the following parameters:

client_id

your application key

client_secret

your application secret

redirect_uri

your callback URL

grant_type

authorization_code

code

your access code

The result will be a JSON hash containing both an access token and a refresh token. The access token may be used to access the API for the next two days, while the refresh token may be used to create a new access token. You should store both of these in your application for future API requests.

Redeeming a Refresh Token

After your access token expires, you will want to redeem your refresh token for a new access token so that your administrator does not need to re-authorize your application. Similar to converting an access code, you would perform an http post to https://app.careerplug.com/oauth/token with the following parameters:

client_id

your application key

client_secret

your application secret

redirect_uri

your callback URL

grant_type

refresh_token

refresh_token

your refresh token

To get started, click Authorize. Paste your access token in the Value field. Click Authorize and Close to continue.