Our APIs are using OpenID Connect 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.

For increased security, our APIs also support DPoP (Proof-of-Possession) , which binds access tokens to a client-held key to reduce token replay risk.

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.

Hubstaff APIs support DPoP (RFC 9449) to prevent token replay attacks by binding an access token to a specific client key pair.

Send the proof as a signed JWT in the DPoP: <dpop_jwt> header.

The signed JWT proof includes the following request-specific claims:

htm

HTTP method of the request (GET/POST/etc)

htu

Full target URI (scheme + host + path). Query and fragment must not be included.

iat

Issued-at timestamp (must be recent)

jti

Unique identifier to prevent replay. Maximum length: 128bytes.

ath

The SHA-256 hash of the access token, Base64URL-encoded without padding.
Required when the DPoP is used together with an access token (API requests using Authorization: Bearer <access_token>).
Not required for requests that do not include an access token (e.g. token refresh).

typ (header)

Must be dpop+jwt

jwk (header)

Public key in JWK format used to verify the signature

openssl ecparam -name prime256v1 -genkey -out private.pem
openssl ec -in private.pem -pubout -out public.pem

{
  "htm": "<HTTP_METHOD>",          // e.g. "GET", "POST"
  "htu": "<TARGET_URI>",            // scheme + host + path (no query/fragment)
  "iat": <unix_timestamp_seconds>,  // must be recent
  "jti": "<unique_id>"              // max 128 bytes
  // If access token is present:
  // "ath": "<ath>"
}

ath = BASE64URL( SHA256( ASCII(access_token) ) )  // no "=" padding

{
  "typ": "dpop+jwt",
  "alg": "ES256",
  "jwk": <PUBLIC_KEY_AS_JWK>
}

DPoP: <signed_dpop_jwt>

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 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.sandbox.hbstf.co

This will request the Open ID Connect Discovery configuration [ https://account.sandbox.hbstf.co/.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 associate with session data)

redirect_uri

The URI to send the user to for 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.

code_challenge

The S256transformation of the code_verifier as defined by the PKCE specification RFC 7636:

code_verifier = high-entropy cryptographic random string (43–128 characters) consisting only of URL-safe characters (A–Z a–z 0–9 - . _ ~) 
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) 

Base64url encoding must be performed without without = padding.
The code_verifier should remain secret on the client and is sent only once, in the token request, to prove possession of the original authorization request.
Optional for constrained environments that can't use the S256 transformation.

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

code_verifier

The original string used to generate the code_challenge in the authorization request.
It is used to validate and confirm the client’s authenticity.
Required only if a code_challenge was included in the authorization request.

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

If DPoP is enabled for your token, also include the DPoP header.

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