Authentication

Applications must be registered and enabled. This can be done from the iCoStaffTime Settings -> Integrations -> Applications.

Online access

Sign into and authorise the registered application for time limited access:

https://www.icostafftime.com/auth/authorize?response_type=token&scope=read+write&client_id=CLIENT_ID

Once authorisation is granted, the browser will be redirected back to the registered URL for this client_id with the following URL query parameters:

• access_token - to access the iCoStaffTime API
• expires_in - number of seconds the access_token is valid for
• scope - the scope authorised by the user
• token_type - the type of token e.g. “Bearer”
• organisation_id - the organisation_id that the user granted the application access for

If there is an error, such as access to the application not being granted, the browser will be redirected back to the registered URL for this client_id with the following URL query parameters:

• error
• error_description

Offline access

Sign into and authorise the registered application for access:

https://www.icostafftime.com/auth/authorize?response_type=code&scope=read+write&client_id=CLIENT_ID

Once authorisation is granted, the browser will be redirected back to the registered URL for this client_id with the following URL query parameter:

• code - use to fetch access and refresh tokens

If there is an error, such as access to the application not being granted, the browser will be redirected back to the registered URL for this client_id with the following URL query parameters:

• error
• error_description

Access and refresh tokens can then be obtained by the application for offline access by performing an HTTP POST using the provided code. Additionally the organisation_id that was approved for access by the user is included in the JSON response.

$ curl -X POST --user CLIENT_ID:CLIENT_SECRET \
"https://www.icostafftime.com/auth/token?grant_type=authorization_code&code=CODE"
{
  "access_token": "XXXXX",
  "expires_in": 1800,
  "refresh_token": "XXXXX",
  "scope": "read write",
  "token_type": "Bearer",
  "organisation_id": "XXXXX"
}

When the access_token token expires, a new one can be obtained by performing an HTTP POST using the previously issued refresh_token.

The previously issued refresh_token will no longer be valid and the new one returned in the JSON response must be used for the next refresh_token call.

$ curl -X POST --user CLIENT_ID:CLIENT_SECRET \
"https://www.icostafftime.com/auth/token?grant_type=refresh_token&refresh_token=REFRESH_TOKEN"
{
  "access_token": "XXXXX",
  "expires_in": 1800,
  "refresh_token": "XXXXX",
  "scope": "read write",
  "token_type": "Bearer"
}