Authentication overview

Our APIs are using OpenID Connect to for authentication.

We use this because it provides a secure method of authentication and builds on the authorization system in OAuth 2.0.

Registering an application

To start using our APIs in your product you need to first create an oauth app.

You will need the following pieces of identification information

Application name
A name to identify the application to your users.
Contact email
A contact email for us to use to contact you for any issues. We may at some point make this accessible to users of your app.
Logo
A logo (max 300px by 300px) for your application. This will be shown to the user to help identify the application.
Homepage URL
This is the main page of your application. This will be shown to the user to help identify the application.

Also you will need a Redirect URL. This is the URL that the user will be sent to after authorizing your app. We require you to pre-register your redirect URLs as we verify your authorization requests against it to prevent hijacking attempts. Redirect URLs should be a full URL and must be HTTPS except for local development using localhost or .test top-level domains.

Redirect URLs
https://app.example.com/oauth
http://localhost:3000/oauth
http://myapp.test/oauth

This can be done by going to going to the oauth apps page and clicking New.

Open ID Connect Discovery

To perform an authentication request you must first request our Open ID Connect configuration from our discovery endpoint.

If you are using a Open ID Compliant client library you should simply need to perform a discovery against https://account.hubstaff.com

This will request the Open ID Connect Discovery configuration

You should cache this information for 1 week. This configuration includes

  1. The authorization endpoint to send your initial request to
  2. What scopes are supported.
  3. The token endpoint
  4. What authorization flows we support
Authorizing a user

To initiate an authorization request, redirect the user to the authorization_endpoint with the following information.

client_id
The client_id of your app.
response_type
Specify code for this as we only support the Authorization Code flow.
nonce
A required unique nonce. This must be different for each authorization request you make. This is used to prevent replay attacks.
state
An optional state value which will be returned back to you (use this to association with session data)
redirect_uri
The URL to send the user to for a handling the authorization request response. This is validated against the list of authorized redirect URLs you configured for the app.
scope
A space delimited list of scopes to request. Examples are openid, profile, email, and scopes for access within the specific API.

The user will be presented with an authorization screen by us showing them what data you are wanting access to. Once they authorize the request we will send them to the redirect_uri with the code and state

Obtaining the access_token

Once you receive a success response to your redirect_uri you use the code in that response to exchange for an access token.

This is done by making a POST to the token_endpoint to retrieve the access_token and refresh_token.

grant_type
Specify authorization_code for this
code
The code you received in the redirect_uri
redirect_uri
Specify the same redirect URL you used in the initial request.
Authorization header
Perform a basic authorization using your client_id and client_secret as the username and password.

On a successful response you will receive

token_type
The token type which will be Bearer
access_token
The access token.
expires_in
The amount of time the access_token will last. Generally 24 to 72 hours. Once this expires you must issue a refresh grant request to obtain a new access_token
refresh_token
The token to use to request an updated access_token when it expires. You must store this with the access_token as it will be required to refresh the token.
id_token
If you specified openid scope, you will receive an id_token that will allow you to request user details via the userinfo_endpoint.
Making API Requests

To make an API request using the access_token you just need to send it in the Authorization header like this

Authorization: Bearer e2f8c8e136c73b1e909bb1021b3b4c29

Refreshing the access_token

To refresh the access_token make a refresh grant request to the token_endpoint.

This is done by making a POST to the token_endpoint .

grant_type
Specify refresh_token for this
refresh_token
The refresh_token you received from the previous request.
scope
The scopes you want to renew. You should generally specify the same scopes you sent for the initial authorization request.
Note You can not request for scopes not originally authorized.
Authorization header
Perform a basic authorization using your client_id and client_secret as the username and password.

On a successful response you will receive

token_type
The token type which will be Bearer
access_token
The access token.
expires_in
The amount of time the access_token will last. Generally 24 to 72 hours. Once this expires you must issue a refresh grant request to obtain a new access_token
refresh_token
An updated refresh_token. Replace the previously stored refresh_token with this new token.