API Reference

Hourfleet is built on a foundation of HTTP REST API’s. This means that anything and everything that you and your customers can do in the Hourfleet App, can also be automated by any system on the internet by calling HTTP methods.

That’s exactly how Hourfleet works.

These are the base URL’s of the API’s that Hourfleet provides for your Car Share:

API Documentation

Detailed documentation about each of these API’s can be found at the above URL’s.

To see the documentation, swap yourcarshare in the above URL’s with the name of your Car Share (or just use demo if you don’t have one yet).

Authorized Access

You need an access_token to call an API

Most of the API’s that Hourfleet exposes require the caller to be authenticated, there are only a few that do not. You can see the security requirements of each API in the API documentation.

Most callers (those who call API’s) in Hourfleet are authenticated with credentials, such as a username and a password or with a client_id and client_secret.

Once authenticated, a caller will receive a token that needs to be transmitted along with the API call (typically in the ‘Authorization’ header of the call).

Authorization: Bearer AAIAAMqDamBCSU7ITHnyx.......

This token is called an Authorization token, and Hourfleet uses the OAuth2.0 authorization scheme for its tokens (called access_token). Its an opaque token. You cannot decode it, or look inside it like other tokens.

Normally, users of the Hourfleet App (https://yourcarshare.hourfleet.com) are authenticated by giving their credentials (username + password) to the Hourfleet App. A ‘Client Application’ like the Hourfleet Web App itself then presents the user’s credentials to Hourfleet servers (along with its credentials) to authenticate user, and an authorization token is issued and returned.

Note: In all cases, in order for a user to authenticate, you also need a trusted ‘Client Application’ to manage the issuance of the token.

The token identifies the caller, and defines what the caller has access to. The token is then passed along with any call to authorize access to any API’s in Hourfleet.

When using an API directly from other tools (like Postman) or from other systems or services on the internet, a users’ credentials may not be directly available for you to use.

You have two standard choices in Hourfleet to get yourself an authorization token that will give you access to API’s.

  1. Direct Authorization: You create a Client Application, that gives you a new set of credentials (client_id and client_secret) that you exchange for a token that gives you access to a restricted set of API’s in Hourfleet. You store those credentials safely (never in public source code), and then use those credentials (client_id + client_secret) whenever you need to get a new authorization token.
  2. Delegated Authorization: You create a Client Application, that gives you a new set of credentials that you use to ask an existing user of Hourfleet to grant you access to their API’s (as them), by having them authenticate and then explicitly authorize you to obtain a token. This token grants you access to any API, as that user to access API’s as that user.

Note: Hourfleet support OAuth2 authorization. It supports the ‘Client Credentials’ grant and the ‘Authorization Flow’ grant. Other grant types are not available.

Direct Authorization

This kind of authorization is granted to Client Applications directly.

Client Applications are created in the Hourfleet App by operators in the ‘Operators’ Dashboard. Their credentials are generated by Hourfleet, and stored by you safely. The credentials are used to obtain a token.

These clientapplication tokens will have access to a restricted set of permissions in Hourfleet. A subset of these permissions can also be requested and granted on each request for a token.

These tokens typically have access to API’s that: control the configuration of your Car Share, manage its users, and have various administrative capabilities, reporting etc.

These tokens will not grant access to act as regular users (or API’s that require a user to be known), since a client application will not have a user profile (They will not have: a name, an email address, a drivers license, nor verifications etc.).

These tokens cannot be used to permit participation in booking, using or owning of cars, etc.

These tokens expire and cannot be renewed. (default expiry 15mins)

The OAuth2.0 flow that implements this kind of authorization is called the ‘Client Credentials’ grant.

Delegated Authorization

This kind of authorization is granted to Client Applications indirectly by an existing user in your Car Share.

This is done by asking the user/person to grant the Client Application access to their account, and typically to some limited set of data within that account (i.e. my profile, my cars, my bookings, etc.).

In this grant process a user (a person) is presented with a user interface that identifies who is requesting access (the Client Application), and what level of access is being requested. A user makes an explicit choice to approve the request or deny it.

(This experience is a familiar experience for most people on the internet today, for example, when Twitter requests access to your Facebook friends list, you login to Facebook and grant Twitter access to your friends list).

Code Grant

Client Applications are created in the Hourfleet App by operators in the ‘Operators’ Dashboard.

These user tokens will have a subset of access to API’s that relate to specific users of the Car Share, and as such the Client Application acts on behalf of the user who has granted them access.

This token may have access to profile, verification data, etc.

This token may allow participation in using and owning cars, etc.

These tokens expire (default expiry 15mins), but can be renewed by using a refresh_token which lasts for much longer. Typically, these tokens are stored and renewed so you can avoid involving the user giving their credentials again to you.

The OAuth2.0 flow that implements this kind of authorization is called the ‘Authorization Code’ grant

Obtaining Tokens

Use either the ‘Client Credentials’ grant or the ‘Authorization Code’ grant to obtain tokens from these URLs:

Note: Remember that tokens have a default expiry of 15mins.

You can use any tool like PostMan to fetch a token.

Using Tokens

Once you have obtained a token using one of the methods above, you will need to include the token in every API call you make.

The token must be put into the Authorization header of the request in this format:

Authorization: Bearer AAIAAMqDamBCSU7ITHnyx.....rest of the token......

Note: If you use Delegated Authorization, you don’t need to ask the user for permission once the token expires, you can use the refresh_token to obtain a fresh token and buy some more time.

Webhooks

If you are interested in receiving notifications from Hourfleet for key events while your Car Share is operating, then you might want to subscribe to some of the webhooks that Hourfleet supports. See Webhooks for more details.