A device is a component that requires software to function. Examples include a modem, display, and position receiver. The Equipment API endpoints allow access to information about paired devices if necessary.

Equipment Make, Type, and Model

In the equipment API endpoints section, we have provided documentation related to our reference database API for equipment makes, types, and models to assist with applications that will be creating third party managed equipment in Operations Center. The API responses from this API are only to provide the appropriate make, type and model IDs and used in the equipment creation request. Please see the Equipment Measurements API documentation section referenced below for information on creating third party managed equipment and sending in measurement data for those devices (if connected to a telematic device).

Related Resources

The measurements resource allows an application the ability to post in measurement data such as speed, GPS location, engine state, odometer, and engine hour values for third party created and managed equipment.

The alerts resource provides the information captured on the telematics terminal when an alert occurred with a machine. These are also referred to as DTCs or Diagnostic Trouble Codes.

A device state report provides the details for the connected telematics device for a specified date range. There are several attributes in included about the state of the telematics terminal and connectivity.

The engine hours resource provides the last reported number of hours that a machine’s engine has recorded. Each response includes a timestamp and the source of that record.

The hours of operation resource provide the durations for which the engine was on or off during a specified time range. The last known state of the machine is also accessible.

The breadcrumbs resource provides detailed equipment locations along with other sensor data for a specified time range. These are recorded as the equipment is working only.

The location history resource provides latitude, longitude, and altitude for a specified time range. These records are given on the telematic device’s regular call intervals.

The John Deere Precision Tech API endpoints use OAuth 2.0 for authentication. OAuth is an open protocol, and these APIs currently only support the authorization code grant type for external applications.

You can also see our sample code for examples of navigating our OAuth 2 authentication code flow.

1. Create an Application on Developer.Deere.com

   You must be a validated John Deere user to create an application on developer.deere.com. If you do not have a John Deere username and password, you can create one using the Create an Account option on our digital tools home page here: https://www.deere.com/en/digital-tools/. You must be able to sign into the developer.deere.com to use the Create Application option in the My Applications section of the website. Please follow the steps of the Create Application workflow on the website before proceeding to the next steps.

   Once your application is created, the Security section of the application Details will provide you with the Application ID and Secret necessary for the next steps to sign your API token requests.

   A note on Redirect URIs (Callback URLs):

   During the creation of the application (or found after creation in the application Details/Security section) you will need to define one or any number of Redirect URIs (Callback URLs). These are required for the OAuth 2 authentication flow. If you do not have this when creating the application, there is an example given in that section when creating the application that you may use for now which is http://localhost:9090/callback

   If Redirect URIs are not added to your application properly or used in the authentication process in a different format than listed in the application details (for example encoded vs non-encoded), your users will experience a 400 Bad Redirect error during authentication.

2. Call the OAuth 2 well-known URL

   With your application client or a web browser window, make a GET request to https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/.well-known/oauth-authorization-server. This URL contains the authorization and token endpoints, as well as the available scopes mentioned in the steps below.

   Sample Response [JSON]

   {
       "issuer": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7",
       "authorization_endpoint": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/authorize",
       "token_endpoint": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/token",
       "registration_endpoint": "https://signin.johndeere.com/oauth2/v1/clients",
       "jwks_uri": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/keys",
       "response_types_supported": [
           "code",
           "token",
           "id_token",
           "code id_token",
           "code token",
           "id_token token",
           "code id_token token"
       ],
       "response_modes_supported": [
           "query",
           "fragment",
           "form_post",
           "okta_post_message"
       ],
       "grant_types_supported": [
           "authorization_code",
           "implicit",
           "refresh_token",
           "password",
           "client_credentials",
           "urn:ietf:params:oauth:grant-type:device_code"
       ],
       "subject_types_supported": [
           "public"
       ],
       "scopes_supported": [
           "ag1",
           "ag2",
           "ag3",
           "eq1",
           "eq2",
           "files",
           "finance1",
           "finance2",
           "org1",
           "org2",
           "work1",
           "work2",
           "openid",
           "profile",
           "email",
           "address",
           "phone",
           "offline_access",
           "device_sso"
       ],
       "token_endpoint_auth_methods_supported": [
           "client_secret_basic",
           "client_secret_post",
           "client_secret_jwt",
           "private_key_jwt",
           "none"
       ],
       "claims_supported": [
           "ver",
           "jti",
           "iss",
           "aud",
           "iat",
           "exp",
           "cid",
           "uid",
           "scp",
           "sub"
       ],
       "code_challenge_methods_supported": [
           "S256"
       ],
       "introspection_endpoint": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/introspect",
       "introspection_endpoint_auth_methods_supported": [
           "client_secret_basic",
           "client_secret_post",
           "client_secret_jwt",
           "private_key_jwt",
           "none"
       ],
       "revocation_endpoint": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/revoke",
       "revocation_endpoint_auth_methods_supported": [
           "client_secret_basic",
           "client_secret_post",
           "client_secret_jwt",
           "private_key_jwt",
           "none"
       ],
       "end_session_endpoint": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/logout",
       "request_parameter_supported": true,
       "request_object_signing_alg_values_supported": [
           "HS256",
           "HS384",
           "HS512",
           "RS256",
           "RS384",
           "RS512",
           "ES256",
           "ES384",
           "ES512"
       ],
       "device_authorization_endpoint": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/device/authorize",
       "dpop_signing_alg_values_supported": [
           "RS256",
           "RS384",
           "RS512",
           "ES256",
           "ES384",
           "ES512"
       ]
   }

3. Acquire an authorization code

   The authorization code is obtained by using the authorization server as an intermediary between the client and resource owner. The client directs the resource owner to an authorization server, and once authorized the server redirects the resource owner back to the client with the authorization code. Along with the GET request to the authorization server URL, you will need to send a response type code parameter, along with OAuth scopes, client ID, state, and redirect URI.

   

   The authorization URL for the user to follow (in a web browser) should look like this:

   GET

   'https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/authorize?response_type=code&scope={scopes}&client_id={clientId}&state={state}&redirect_uri={redirect_uri}

   A note on OAuth Scopes and Data Permissions:

   In the  Dev Docs API sections, the required OAuth scopes will be referenced for each method and endpoint. For the OAuth access token, you must request the required scopes for each endpoint your application will be using. DO NOT request all scopes available on our authorization server as not all are required for your application, and your users should be prompted to only accept scopes (permissions) necessary for the API calls you will be making.

   The OAuth scopes your application requests initially for a user access token will directly relate to the permissions granted when the user makes the organization connection to your application. Please refer to the scopes table below. These scopes directly relate to user, partner, and Connected Software Company data access permissions referenced in Team Manager.

   Note: If the user has less permissions in their own organization(s) or their partner organization(s) than the scopes you are requesting initially, only the user’s permission set will be assumed in the connection from the selected organization to your application. We will not grant more permissions to your application than the connecting user has.

   Once the connection from the user’s organization is made to your application, you may request a higher-level scope or new scopes for the user access token, however, the connection permissions must also be adjusted by the user in https://connections.deere.com for the requesting application. Before adjusting those permission levels in the Connections website, the user must have obtained those permissions in their own organization or must be shared by the partner organizations that are currently connected.

   Scope	User/Connection Permission	Description
   org1	Organization Management Access Level 1	View Staff, Operators, and Partners
   org2	Organization Management Access Level 1 Organization Management Access Level 2	View Staff, Operators, and Partners Modify Staff, Operators, and Partners
   eq1	Equipment Access Level 1 RDA Setup & WDT	View Equipment Remote Display Access Setup File Creator, Products, and Wireless Data Transfer
   eq2	Equipment Access Level 1 Equipment Access Level 2 Equipment Access Level 3 RDA Setup & WDT	View Equipment Edit Equipment (also View Detailed Machine Measurements) Manage Equipment Remote Display Access Setup File Creator, Products, and Wireless Data Transfer
   ag1	Locations Access Level 1	View Locations (Clients, Farms, Fields and Associated Data)
   ag2	Locations Access Level 1 Locations Access Level 2	View Locations (Clients, Farms, Fields and Associated Data) Analyze Production Data (Website Access Only)
   ag3	Locations Access Level 1 Locations Access Level 2 Locations Access Level 3	View Locations (Clients, Farms, Fields and Associated Data) Analyze Production Data (Website Access Only) Manage Locations & Production Data (Website and API Access)
   files	Files API Access Equipment Access Level 3 Setup & WDT	Files API Access (ag3 scope also required for most file types) Manage Equipment Setup File Creator, Products, and Wireless Data Transfer
   finance1	Financial Access Level 1	View Financials
   finance2	Financial Access Level 1 Financial Access Level 2	View Financials Manage Financials
   work1	Work and Crop Plans Access Level 1	View Work and Crop Plans
   work2	Work and Crop Plans Access Level 1 Work and Crop Plans Access Level 2	View Work and Crop Plans View Work and Crop Plans
   offline_access	API Authentication Only	Request a Refresh Token

   To summarize the Authorization Code steps:

   1. The customer initiates a request for data from a client application, and the client sends an OAuth request to the authorization server with the proper headers.

   2. The customer is redirected to the John Deere sign-in page.

   3. The customer signs into John Deere, and the request is redirected back to the authorization server.

   4. The customer is then presented with the scope allowance screen. (During first token request, or with modified scopes)

   5. Scope acceptance is sent back to the OAuth server, and the customer is then redirected back to the client application with the authorization code.

4. Acquire an Access Token

   Once the application has the authorization code, the client then requests an access token from the token server by sending a grant type authorization_code parameter, along with the authorization code, a redirect URI, and the client credentials. The authorization server authenticates the client and issues an access token and a refresh token (only if offline_access scope was requested in the previous step). The access token will expire after 12 hours after which it must be refreshed (see the last step).

   

   POST

   https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/token

   Content-Type: application/x-www-form-urlencoded

   • grant_type=authorization_code

   • code={auth_code_from_authorize_call_response}

   • redirect_uri={redirect_uri}

   • client_id={client_id}

   • client_secret={client_secret}

5. Post authorization redirect to enable organization access

   Once the client obtains a valid access token, there is an additional step required to enable organization data access for your client application. If this step is skipped, the client will receive a 403 Forbidden response when trying the access data for any organization to which the user has access

   

   1. Make a call to GET /organizations. If you see a ‘connections’ link in the response, your client has not granted access to that organization.

      Note: A user may have access to multiple organizations but may not enable access to all of them. A ‘connections’ may always be returned for an organization the user chooses not to allow your application access to.

      Example Response:

      [
        {
          "@type": "Organization",
          "name": "Spahn Ranch",
          "type": "customer",
          "member": true,
          "internal": false,
          "id": "283480",
          "links": [
            {
              "@type": "Link",
              "rel": "self",
              "uri": "https://apiqa.tal.deere.com/platform/organizations/283480"
            },
            {
              "@type": "Link",
              "rel": "connections",
              "uri": "https://connections.deere.com/connections/deere-sld8shg8ee0o8ns8nhdh88hn/select-organizations"
            }
          ]
        }
      ]

   2. Redirect the user to Operations Center (in a web browser) using the URI provided in the ‘connections’ link. You can also provide a redirect_uri query parameter so the user will be redirected back to your application after the organization selection process is completed. The redirect_uri that is provided must match one of the Redirect URIs listed in your application profile. The redirect_uri must also be URL encoded (i.e. “https://example.client.com/callback” should be passed as “https%3A%2F%2Fexample.client.com%2Fcallback”).

      Example URI: https://connections.deere.com/connections/{clientId}/select-organizations?redirect_uri={redirectUri}

   3. The user selects the organization(s) to which your client can have access.

      

   4. Once the organization selection is complete, the user will be redirected back to your application based on the redirect_uri query parameter that was provided. If the redirect_uri query parameter is not provided or is invalid, then the user will remain on the Connections application in Operations Center.

      Additionally, the GET /organizations endpoint will no longer include the ‘connections’ link and instead will include a ‘manage_connections’ link. This will link into the management modal in Connections for the application in the organization. Having the ‘manage_connections’ link implies that a connection between an application and organization is fully established.

      Example Response:

      [
        {
          "@type": "Organization",
          "name": "Spahn Ranch",
          "type": "customer",
          "member": true,
          "internal": false,
          "id": "283480",
          "links": [
            {
              "@type": "Link",
              "rel": "self",
              "uri": "https://apiqa.tal.deere.com/platform/organizations/283480"
            },
            {
              "@type": "Link",
              "rel": "manage_connections",
              "uri": "https://connections-qual.deere.com/connections/deere-sld8shg8ee0o8ns8nhdh88hn/connections-dialog?orgId=283480"
            }
          ]
        }
      ]

   5. Avoid getting into a redirect loop and only perform the connections redirect one time per user session. There are a few scenarios in Operations Center when a user either decides not to or is unable to complete the organization selection step. If your application does not have access to an organization after completing the connections redirect, we suggest that you inform the user that the connection was not completed and they may need to login to Operations Center to modify the Connection manually.

6. Use the access token to call API resource

   Once the client obtains the valid access token and the user has enabled organization access for the client, they can use this token to call the appropriate resource server (API) to obtain the data needed.

   

   For API call structure, parameters, and headers, refer to the Dev Docs section.

   All your API calls should include an Authorization: Bearer {token} utilizing the obtained token.

7. Setup Token Refresh Process

   The client application will need to pass a refresh token to the authorization (token) server to obtain a new access token before the access token expires (12 hours). For this you will pass through a refresh_token grant type parameter, along with the refresh_token to the token server.

   Even if the customer did not request a resource call, the client would need to initiate a periodic refresh of this token to keep it 'hot'. The refresh token will expire after 365 days if it is not used. If the refresh token expires, the customer will need to re-authenticate. As long as you continue to refresh the access token with this refresh token, it will remain active indefinitely (unless the customer removes all organization connections on https://connections.deere.com to your application).

   POST

   https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/token

   Accept: application/json

   Content-Type: application/x-www-form-urlencoded

   • grant_type=refresh_token

   • refresh_token={refresh_token}

   • redirect_uri={redirect_uri}

   • scope={scopes}

   • client_id={client_id}

   • client_secret={client_secret}

Postman is a third-party API client, which you can use to test your John Deere API calls. You may use the Postman website or the desktop application for calling APIs while in Sandbox to see and follow REST API responses. Other API test clients may work for this as well. The below instructions will provide the initial setup steps to get Postman configured and obtain an OAuth 2 token.

1. Download and install Postman on your computer (link above), or you may use the web version.

2. Open Postman, click on Settings at the top, and in General settings turn off all of the Headers options.

3. In the top nav section of the Postman client application, you can hit the + sign to add a new request to your console.

4. In the Auth section of that new request tab, there is a dropdown to select the type of authorization you’ll be using. Select the OAuth2 option.

5. The screen will change, and you will see Type is set as OAuth 2.0.

6. Add auth data to should be set as Request Headers.

7. Header Prefix should be set as Bearer.

8. Within the Configure New Token section, you will need to add values to each of the fields or configure the options before selecting the Get New Access Token button (or it will error out).

1. Add a Token Name (can be anything).

2. Leave the Grant Type as Authorization Code.

3. The Callback URL for redirecting the authorization code back to Postman is https://www.getpostman.com/oauth2/callback. The Callback URL can be set to anything in this example. Remember that if you will be using this Postman callback URL, it (and any other Callback URL you use) will need to be synced with your OAuth client. See step 2 in this document for help in syncing this Callback URL with your application.

4. The Auth URL and Access Token URL can be found with opening a new Postman request window and doing a GET on this URL https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/.well-known/oauth-authorization-server. No Auth is needed for this GET request. You can also open this URL in any internet browser window.

5. For the Client ID and Client Secret Developer.Deere.com, login, and access your application profile in the "My Applications" section.

In the Details window, under the Security section, you will find this information. What Postman calls the Client ID is called "Application Id" in this window. What Postman calls the Client Secret is called "Secret" in this window. Copy the necessary information into the Postman token section.

6. The Scope box should be populated with only the scopes require for the API calls you are making (space delimited). The scopes required for your API calls can be found in the Dev Docs section of every API under each endpoint’s documentation.

7. State is an opaque value to prevent cross-site forgery. Enter any unique string in this box (ex. 12345).

8. For Client Authentication, this option should be set to Send client credentials in body for this example. (not selecting this option will result in an error)

9. Once the steps above are complete, press the Get New Access Token button to proceed to the John Deere sign in page where a valid Operations Center user can sign in. If this is the first time the user is obtaining an API token for your application, they will be presented with the scopes acceptance screen, to which they must choose Allow Access (Don’t Allow will result in a token with no assigned scopes).

In the Details window, the first two pieces of information that OAuth requires are found in the Application Details section (illustration below). What Postman calls the Client ID is called "Application Id" in this window. What Postman calls the Client Secret is called "Secret" in this window. Copy the necessary information into the Postman token section.

10. Once the token is obtained and shown in the Postman screen, select the Use Token button to apply the token to your current API call. (you do not need to configure Authorization headers on the API call, as Postman will do this for you)

11. The next step is to enter the URL of the API call and configure an Accept header. To test, please configure the API URL to be GET https://sandboxapi.deere.com/platform/organizations. In the Headers section, please configure an Accept header with a value of application/vnd.deere.axiom.v3+json. (you may leave the default Postman headers in the request, if applicable)

12. Only once all the steps above are completed, can you hit the Send button in the API request to make the API call and receive a 200 OK response and response body.

13. If you can’t complete this process or have any questions, please feel free to use the Support button in the top navigation of the page to contact us.

When a Precision Tech API returns a collection of objects, it wraps the response in a CollectionPage object. This wrapper object has three properties:

• Integer total: An integer value that represents the number of available values.

• List<Link> links: A collection of links. If the response was paginated, this will contain 'nextPage' and 'previousPage' links.

• List<T> values: The actual object values returned by the API.

By default, collections are paginated. Each page of data contains 10 values. The response will contain nextPage and previousPage links, which can be followed to view the entire response. The last page of data will not have a nextPage link. Please note that not all responses from each API are paginated or accept the page size parameters below.

Page Item Limit

You can control the page size by adding an itemLimit parameter to your request url. The value for this parameter should be in multiples of 10 up to 100 (max limit). You can set this by appending ?itemLimit=100 to the end of the request url.

Page Offset

You can control what page the response begins with by adding a pageOffset parameter to your request url. You can set this by appending ?pageOffset=0 to the end of the request url. The value used for this parameter should be in line with the item limit you are requesting. By default the page size is 10, so when not using the itemLimit parameter, this value should be in multiples of 10 (10,20,30, etc.). If you are using an itemLimit of 100, the value should be in multiples of 100 (100,200,300, etc.)

Disabling Paging

If you prefer, you can disable pagination entirely. The API response will still wrap responses in a CollectionPage object, but you would receive the entire collection at once. To disable pagination, add a request header named x-deere-no-paging and set its value to true. If you will be repeatedly polling an endpoint for updated data, consider using eTags instead of disabling pagination.

When a client application is making requests to John Deere APIs, it will encounter HTTP response errors that should be handled appropriately. Below you will find most of these errors and instructions on handling them.

400 Bad Request

HTTP Code: 400
Response code: Bad Request

This error means that either the POST/PUT body used in the request is incorrect, or if this error is seen in the OAuth 2 POST /token request, it means the refresh token is invalid. Before contacting API Support, please attempt to update the request body or get a valid token for the user. Please see the OAuth 2 documentation here.

401 Unauthorized

HTTP Code: 401
Response code: Server Authorization Failed

This error means that either the application does not have a license for the endpoint, or the user token is expired. Before contacting API Support, please attempt to get a valid token for the user, or use the refresh token process to get a new access token. Please see the OAuth 2 documentation here. Information about what APIs a client application can call by default are listed here, and all other APIs listed on the website are only accessible via a given license.

403 Forbidden

HTTP Code: 403
Response code: Access Denied

This error pertains to the user not having access to this resource. You should only request resources found while navigating the REST endpoints for the user. If the client calls for a resource the user does not have access to, the request will be denied. You can prevent this error by beginning your calls with /platform, and following the returned links to discover resource IDs available to the user (most are found under the /organizations link).

HTTP Code: 403
Response: The client does not have a proper access for this API

This error relates to missing OAuth 2 scopes for the user token. Along with this error code, you will see the client ID, license needed, and read/write/delete scopes needed for that license to make the corresponding requests.

HTTP Code: 403
Response: Requested org is in a restricted state

This error relates to our updates Orgs Terms & Conditions process. We have a guide for handling these requests here.

404 Not Found

HTTP Code: 404
Response code: The requested resource was not found

This error means that the resource ID requested is not valid. All resource IDs should be parsed from API responses immediately before requesting access to it. If IDs are stored for long periods of time, user access to that resource could change or be removed.

429 Too Many Requests

HTTP Code: 429
Response code: HTTP_TOO_MANY_REQUESTS

When the John Deere Servers are overwhelmed by requests, clients may receive a HTTP 429 response. That response may include a "Retry-After" header with a numeric value indicating the number of seconds the client should wait before trying again. When you receive a 429 response with that header, you have to wait at least for the specified time before retrying the request. If a customer is actively waiting for the result, you may need to return an error instead of waiting. If your application is fully asynchronous, always wait the Retry-After amount.

503 Service Unavailable

HTTP Code: 503
Response code: : HTTP_SERVICE_UNAVAILABLE

When John Deere Servers have a backend or server problem, they MAY return a corresponding Retry-After header along with a 503 response. If a 503 is returned without a Retry-After header then John Deere Servers cannot estimate a reasonable recovery time. Your application should enter an exponential back-off loop or return an error in this case. If a Retry-After header is returned, wait the number of seconds given and try again

For all other possible status codes, please refer to this resource that is publicly available (provided by Wikipedia).