README

This repository contains a simple sample cli tool that shows off how to access the Hubstaff public api via PHP.

The core access is all done via the php-openid-client package.

Open ID Discovery

The Hubstaff account system uses the Open ID Connect discovery protocol to allow an application to easily query what the token endpoint, authorization endpoints, etc. are. Thus you only need to know the authentication domain (https://account.hubstaff.com/) and the API endpoint url (https://api.hubstaff.com/)

The example code in client.php fetches and caches this discovery data for 1 week. This way it does not need to be constantly fetched.

Token persistence

This demo has a simple way of managing the API token. It simply stores it in json file that is read from on startup and written when tokens are refreshed.

A proper storage should have locking around read and write. And also the code should lock and re-read the state file when refreshing in case another process already refreshed the token. e.g. a proper refresh token flow should be

lock
re-read state and load the token
if the token is no longer expired or near expiring use the new token (another process refreshed)
otherwise refresh the token
save
release lock

Client app vs Personal access token

The Hubstaff account system's personal access token is designed to work very similarly to our client apps in that they both produce short-lived access tokens that must be refreshed periodically.

The code in client.php is an example on how to accomplish this task using disk access as the permanent token storage. If you have other mechanisms for storage you can implement that in the saveState and loadState methods.

Personal access token use

The default setup in api.js is to use a personal access token. To use create/edit the configState.json so that it contains the following entry.

{
    "token": {
        "refresh_token": "personal access refresh token goes here"
    }
}

Then when the api.js makes a request it will automatically refresh to acquire an access token as needed and persist it to the configState.json between executions.

Setup the configState.json as defined above Then run the cli_tool sample like this

php client.php

And this will dump out the "v2/users/me" endpoint

serg-php / public-api-hubstaff

Maintainers

Details

README

Open ID Discovery

Token persistence

Client app vs Personal access token

Personal access token use