Authentication

At Fieldwire, we use a combination of refresh and access tokens to secure our API:

Refresh tokens are long lived and only used to generate new access tokens
Access tokens have limited lifetime and protect all our API endpoints

These are the steps to follow to manage authentication:

Acquire refresh token from Fieldwire's web app
Generate access token using the acquired refresh token
Make authenticated API calls using the generated access token
When the generated access token expires, go back to step (2) and repeat

Let's look at each of those steps in detail

Acquire refresh token

Refresh tokens are also called API keys or API tokens in Fieldwire. They can be acquired from your account page. In case API access is not enabled for your account, you can follow the steps described in this help article to enable API access & then acquire refresh tokens.

Note: it is expected that you store this refresh token and use it until it expires. See this section below for more info on expiring tokens.

Generate access token using the acquired refresh token

A refresh token can be used to generate an access token (which is a JWT) using this endpoint

curl --request POST \
     --url https://client-api.super.fieldwire.com/api_keys/jwt \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{"api_token": "<refresh_token or api_token>"}'

{
  "access_token": "<access_token>"
}

Make authenticated API calls using the generated access token

The access token generated in the previous step can be used to authenticate any subsequent API call. This is true until the access token expires which could be anywhere from a few minutes to few hours. Fieldwire might change the time to live of these tokens at any time without prior notice

curl --request GET \
     --url https://client-api.us.fieldwire.com/api/v3/projects/d2e57ef9-5315-4fdb-bc56-8c56983788ce \
     --header 'Fieldwire-Version: 2023-11-30' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <access_token>'

{
  "deleted_at": null,
  "created_at": "2023-11-08T03:45:19.829Z",
  "updated_at": "2023-11-08T03:45:19.842Z",
  "account_id": 1234,
  "code": null,
  "color": "#F9CD39",
  "id": "d2e57ef9-5315-4fdb-bc56-8c56983788ce",
  "name": "Example project - 1",
  "plan_name": "Enterprise",
  ... 
}

How to handle access token expiration?

After the lifetime of a generated access token runs out, the subsequent call using that token will fail with401HTTP response. Once this happens, the steps defined above can be used to:

Generate a new access token using the already acquired refresh token
Make subsequent authenticated API calls using the newly generated access token