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": "[email protected]_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:
Field | Description | Format |
---|---|---|
bizName | Your user's business's name, if applicable. Useful if your integration will be utilizing Hurdlr's Customizable User Interface or Hurdlr's Invoicing API. | Any string |
bizType | Your user's business type, if applicable. Useful if your integration will be utilizing the Business-specific Deduction Finder or the Customizable User Interface. | Must be one of the following: "DRIVER", "REAL_ESTATE_AGENT", "INSURANCE_AGENT", "FREELANCER", "HOST", "RETAIL", "E_COMMERCE", "SALES", "CONSULTANT", or "OTHER" |
entityType | Your user's entity/formation type | Must be one of the following: "SOLE_PROPRIETORSHIP", "LLP", "LLC", "S_CORP", or "C_CORP" |
language | Your user's 2-digit language code. Useful if your integration will be utilizing the Customizable User Interface. | Must be one of the following: "EN", "ES", "FR" or "ZH" |
2. Receiving the user's access_token
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 ofContent-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.
Updated 9 months ago