OAuth

The FieldInsight API supports the OAuth 2.0 protocol to provide secure access to its resources. Specifically, it implements the Authorization Code Grant flow, which is ideal for server-side applications. This flow adds an extra layer of security by exchanging an authorization code for an access token. Sensitive credentials such as usernames and passwords are never exposed directly to the client application, enhancing overall security.

Authorization Code Grant Flow

In the Authorization Code Grant flow, the client application must first obtain an authorization code from the FieldInsight authorization server. This code is then exchanged for an access token and a refresh token. Here’s how the process works:

1. Request Authorization Code

To initiate the process, the client redirects the user to the FieldInsight authorization URL:

https://app.fieldinsight.com/oauth/authorize?response_type=code&client_id=<client_id>&redirect_uri=http://localhost/oauth&state=state

client_id: This is the unique identifier for your application.

redirect_uri: This is where FieldInsight will send the user after they authorize the application.

state: An optional, random string to protect against CSRF attacks.

Upon successful authorization, the authorization server will redirect the user back to the specified redirect_uri along with the authorization code.

2. Exchange Authorization Code for Access Token

Once the authorization code is obtained, the client can exchange it for an access token and refresh token by sending a POST request to the token endpoint:

This request must include the following parameters:

grant_type: Set to authorization_code.

client_id: Your application's client ID.

client_secret: The secret associated with your client ID.

code: The authorization code obtained from the previous step.

redirect_uri: The same redirect URI used in the authorization request.

If successful, the response will contain both the access token and a refresh token.

3. Access Token Expiry

The access token is your gateway to access FieldInsight API resources. However, it is short-lived and expires after 10 hours. After expiration, you will need to use the refresh token to obtain a new access token.

4. Refreshing the Access Token

When the access token expires, you can request a new one using the refresh token by sending the following POST request to the token endpoint:

grant_type: Set to refresh_token.

refresh_token: The refresh token issued alongside the original access token.

client_id and client_secret: Your application's credentials.

This request will return a new access token, which you can use to access the API endpoints again.

Accessing the API with the Access Token

To access any of the API’s protected endpoints, you must include the access token in the Authorization header of your request. For example:

Authorization: Bearer <access_token>

This ensures that FieldInsight knows who is making the request and that they are authorized to do so.

Authorization Code Grant Flow#

1. Request Authorization Code#

2. Exchange Authorization Code for Access Token#

3. Access Token Expiry#