All Climate FieldView APIs are accessed using HTTPS protocol, which protects all data, including usernames, passwords, email addresses, and yield data, during transport to and from Climate’s systems. We adhere to transport-layer security (TLS) 1.2, the latest protocol.

All Climate FieldView APIs use the designated authorization framework, OAuth2. Tokens generated during the OAuth2 process ensure that the user is authorized to access the requested resources. This protocol maintains data integrity and protects our shared users’ sensitive information. Of the many authorization frameworks available, OAuth2 is the most versatile and secure because it’s lightweight, works well with JSON REST APIs, and supports many types of clients, such as web apps, mobile apps, IoT devices, and backend services.

Every call to Climate FieldView APIs requires an access token. Access tokens are generated using an OAuth2 authorization code grant—typically authorization_code, client_credentials, or refresh_token grants.

To generate an access token, your webapp must direct users to the “Log in with FieldView” page. Once users authenticate on the Climate FieldView site, they’ll be redirected back to your app with a code you’ll use to retrieve the required access tokens. Then users can call the Climate FieldView API.

Here’s the Interactive login workflow:

1. “Log In with FieldView” (authorization request)
   1. The user arrives at your site and clicks the “Log in with FieldView” button. Clicking this button navigates the user's browser to the Climate FieldView login page on climate.com (whitespace added for clarity): 

      https://climate.com/static/app-login/index.html
      ?scope=${scope}
      &response_type=code
      &redirect_uri=${redirect_uri}
      &client_id=${client_id}

      scope: This is the list of scopes corresponding to the endpoints you intend to call after authenticating. This list should be as specific as possible, since the user will be asked to grant permissions for each requested scope. The value must be a space-delimited, URL-encoded list (e.g., fields:read imagery:write). Click Authorize on the API documentation page for a list of scopes corresponding to each resource/endpoint.

      redirect_uri: The redirect_uri in the above query must be a fully qualified, URL-encoded URI on your server. 

      client_id: This is the OAuth2 client ID provided to you by the Climate Corporation.

      response_type: This specifies this request is for an authorization code. 

      1. The user enters a valid Climate FieldView username and password and clicks Log In.
      2. The user is then prompted to confirm that the partner app should be allowed access. This prompt is branded with your logo. The user clicks Allow.
2. Redirect back to partner site (authorization response)
   
   1. The user's browser is redirected back to your site.
   2. After the user authenticates and allows access to the partner app, the redirect_uri specified in the authorization request receives a single query parameter named code. You then use this code to request an access token from Climate, via a backend web service call.
   3. This temporary code, which expires in about 1 minute, is used to generate the initial access token.
3. Access token request and response
   
   1. Using the code provided in step 2, your application requests an access token and refresh token pair. The code must match the parameter value received by the callback URI (redirect_uri) in step 2. POST with content type application/x-www-form-urlencoded the following information to https://api.climate.com/api/oauth/token:

      grant_type=authorization_code&redirect_uri=${redirect_uri}&code=${code}

      Note that this is not a JSON payload.
   2. Your application provides the access token on each subsequent call to the API to identify the user on whose behalf the call is made, thereby authorizing the resource request.

Additionally, an authorization header must be sent with the POST. A Climate Corporation employee must create an OAuth2 client ID and secret pair for use in your app. The value of the authorization header must be as follows: 

Basic {base64_encode($clientId:$clientSecret)} 

Note the single space between “Basic” and the base64-encoded value. Here, courtesy of Wikipedia, is an example of a basic authentication header:

Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

The Climate OAuth2 token API will return a JSON response containing an access_token and a user. The access_token is required for all future Climate FieldView API calls. Use the access_token in the authorization header on all Climate FieldView API calls with the following format: Bearer $access_token.Here’s an example:

Authorization: Bearer 435a5f91-617a-427d-8609-3b43f5ad52d4

If the Authorization header is missing, an HTTP status code 401 is returned, with the following response body:

{"message": "Unauthorized"}

Access tokens expire 4 hours after issue. To generate a new access token, your application will make a request similar to the process used in step 3 (access token request and response), but will provide the refresh token instead of the code.

The /token endpoint returns a refresh_token (along with the access_token). The refresh token can be exchanged for a new access_token (and a new refresh_token) using the same /token endpoint. The access token is good for only 4 hours, but the refresh token is good for 30 days or until it’s exchanged. You can then discard the expired token. Refresh tokens can be used only once. 

Use the newly issued refresh token the next time you need an access token. By exchanging the refresh token for a new one at least every 30 days, your application can extend a user’s session as long as needed. To avoid forcing the user to log in with FieldView in the future, update the access/refresh token pair at least every 30 days, so that the refresh token is never allowed to expire.You still need to supply your basic authorization header, composed from your client ID and secret.

To trade in a refresh_token, make the same POST request to https://api.climate.com/api/oauth/token that you made initially with the activation code, but with a new grant type. The body of the request should look like this:

grant_type=refresh_token&refresh_token=${your_refresh_token}

The process of acquiring an access token, calling the API, and refreshing the token is shown in the accompanying diagram.

The first access token and refresh token pair is generated after the user authenticates with FieldView as part of the access token request and response process. The refresh token must be housed in persistent storage. This is important because without the refresh token, the user will have to log in again when the access token expires.

The access token is used for all Climate FieldView API calls in the context of a user session, which may be initiated either by the user or through a backend service. When the next user session begins(assuming it's more than 4 hours later), the refresh token generates a new access token/refresh token pair. Store the new refresh token, and use the access token to perform all subsequent Climate FieldView API calls. Repeat this process each time a user session is needed to make a batch of API calls. To ensure the user does not need to log in with FieldView again, be sure to exchange the refresh token for a new one at least every 30 days even if no API calls are made during that time.

Here are some important tips to keep in mind when working with access and refresh tokens:

• Refresh tokens are single-use items. Once a refresh token is exchanged, it is no longer valid.
• If a refresh token is lost because of failure to record it in persistent storage, the user must log in again using the "Log in with FieldView" process.
• Only one process or thread should handle the token refresh for a given user. The token can be lost if multiple processes handle it. 
• Access tokens are valid for 4 hours from the time of issue. You can either refresh tokens before they expire or wait for failure and refresh as needed. Either approach is acceptable.

Several layers of security protect Climate FieldView APIs from DoS attacks. These security measures ensure availability for all partners during an attack, whether intentional or unintentional, such as a runaway process. API keys are used for throttling (rate limiting).

In addition to the OAuth client ID and secret pair, Climate supplies an API key during onboarding. This API key controls throttling (429 responses) and records usage metrics.

The following header is required on all calls to the Climate FieldView APIs:

X-Api-Key: <partner-name>-b6b21726-a1db-46b9-be56-16532a0452d2

If the X-Api-Key header is missing or invalid, a 403 HTTP status code will be returned with the following response body:

{"message": "Forbidden"}

Invalid Scope

400 Bad Request
{
    "error_description": "Invalid Scope!",
    "error": "invalid_scope"
}

If you’re trying to get a token with multiple scopes, make sure the scopes are space delimited and URL encoded. For example, if you need a token with scope fields:read and fields:write, use fields:read fields:write URL encoded to fields%3Aread%20fields%3Awrite.

Request Body Contains Authorization Information

400 Bad Request
{
    "error_description": "Request body and headers contain authorization information",
    "error": "invalid_request"
}

Don’t include your client_id and client_secret in the body of the request. That information should be part of the Authorization header. Use the following basic format: {base64_encode($clientId:$clientSecret)}

Inactive Authorization Code

400 Bad Request
{
    "error_description": "Inactive authorization code received from token request",
    "error": "invalid_grant"
}

Authorization codes can be used only once. To get a replacement token, get another authorization code or submit a refresh token request.

Grant Is Invalid When Using refresh_token

400 Bad Request
{
    "error_description": "Provided Authorization Grant is invalid",
    "error": "invalid_grant"
}

A refresh token can be used only once, so be sure to use an unused token. Alternatively, you can request an authorization code for a replacement token.

Callback URI Mismatch

400 Bad Request
{
    "error_description": "Callback url mismatch",
    "error": "invalid_grant"
}

The redirect_uri used in the OAuth request is different from the one in the authorization code request.