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.

We also provide a personal access token system as well. This better targets server-side script applications that can not easily utilize the interactive login we enforce by OpenID Connect + OAuth 2.0.

The personal access token system is slightly different from other applications in that the token you receive is a refresh token which has a long expiration time (90 days). Read more on how to obtain an access token from a personal access token refresh token.

We recently switched to utilizing a JWT to wrap our token identifiers. This allows several benefits.

1. The tokens can be verified against our server to ensure they came from us. This can be done utilizing the keys in the jwks_uri .
2. The token can be unpacked to get data that is stored within. We currently store the time the token was issued, the expiration and the list of scopes the token has been granted.

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 URI. This is the URI that the user will be sent to after authorizing your app. We require you to pre-register your redirect URIs as we verify your authorization requests against it to prevent hijacking attempts. Redirect URIs should be a full URI and must be HTTPS except for local development using localhost or .test top-level domains.

Redirect URIs

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.

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 [ https://account.hubstaff.com/.well-known/openid-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

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 URI to send the user to for a handling the authorization request response. This is validated against the list of authorized redirect URIs 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

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 URI 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.

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

Authorization: Bearer e2f8c8e136c73b1e909bb1021b3b4c29

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 optional set of scopes you want to renew. If omitted then the same scopes originally issues will be used.

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.

Personal access tokens can be managed on the personal access token page.

When you create a personal access token you will receive a refresh token identifier. Before connecting to our API, you first need to exchange that for an access token. Exchanging the token is done by calling the standard OAuth 2.0 token endpoint and using the refresh_token grant_type.

This is done by making a POST to the token_endpoint .

Note that this is nearly identical to the standard refresh_token call

grant_type

Specify refresh_token for this

refresh_token

The refresh_token you received from creating the personal access token or from a previous refresh_token request.

above, except we do not specify a client_id nor secret when using personal access tokens.

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 (in seconds). 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.