Registering a User

The first step to consuming any of the Hurdlr API products is to register your user with the Hurdlr API. Per OAuth 2.0 protocol, this request should contain your client_id and client_secret. This API call should be invoked from your server, to protect your API credentials from being exposed on the client-side.

The response will contain an OAuth 2.0 access_token, which should be added to your request headers (per the OAuth 2.0 protocol) for all subsequent API requests on behalf of this user.

1. Registering a user

curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v5/auth/account \
  --header 'Content-Type: application/json' \
  --data '{
  "userId": "YOUR_INTERNAL_USER_ID",
  "email": "your_user@their_domain.com",
  	"firstName": "Jane",
    "lastName": "Doe",
  	"countryCode": "USA",
  	"client_id": "${client_id}",
    "client_secret": "${client_secret}"
  }'

Optional data parameters, for more personalized functionality, are listed below:

2. Receiving the user's access_token

The response from POST /account contains the user's access_token, which you should store in your database, and associate to your user.

{
  "oAuth": {
    "access_token": "YOUR_USERS_NEW_ACCESS_TOKEN",
    "refresh_token": "YOUR_USERS_REFRESH_TOKEN",
    "expires_in": 7776000,
    "created_at": 1623957934,
    "scope": "token"
  }
}

3. Refreshing the user's access_token

Per OAuth 2.0 spec, the above response also contains a refresh_token and expires_in field. You can calculate the expiration date/time of the access_token by summing the created_at and expires_in fields, which will yield a specific date/time in UNIX Epoch time.

Per OAuth 2.0 spec, when an access_token expires, you can refresh the token using the /token endpoint as follows:

curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v5/auth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'refresh_token=YOUR_USERS_REFRESH_TOKEN'

The response from POST /token uses the same format as the /account response.

📘

URL-encoded Parameters

While the bulk of the Hurdlr API uses Content-Type: application/json, the OAuth 2.0 spec generally favors using URL-encoding for /token implementations; hence the usage of Content-Type: application/x-www-form-urlencoded above.

4. Removing a user

If your user deletes their account within your app, then you will want to remove their account from the Hurdlr API as well:

curl \
  --request DELETE \
  --url https://sandbox.hurdlr.com/rest/v5/auth/account \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \

Once the above DELETE call is made, the user's data will be inaccessible. After 30 days, it will be permanently deleted. In that period of time, you may restore that user's account if needed (e.g. if the user accidentally deleted their account). Since the user's account was previously removed, Hurdlr's standard Authentication (with the access_token in the header) will not work; instead, the accessToken will need to be included in the POST data:

curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v5/auth/restoreAccount \
  --header 'Content-Type: application/json' \
  --data '{
  	"access_token": "${access_token}",
  	"client_id": "${client_id}",
    "client_secret": "${client_secret}"
  }'

The response from POST /restoreAccount uses the same format as the /account response.