The ISO 15143-3 (AEMP 2.0) API retrieves machine data according to the ISO standard. Before you access this API, you must have set up a username, password, and organization for you through Operations Center. Ask your John Deere Dealer or submit a support ticket if you require assistance.

Read the ISO standard (15143-3) document for more information. Updates can be found and downloaded here.

To get an app profile for accessing this API, please visit the My Applications section.

John Deere is continually developing additional data points in the ISO spec. Please check back with us later for any changes and additions. You are also invited to let us know what else you need. Please use the Support button to communicate with us.

• Header Information

• Last Known Location

• Locations

• Operating Hours

• Cumulative Operating Hours

• Cumulative Idle Hours

• Cumulative Fuel Used

• Fuel Remaining Ratio

• DEF Remaining Ratio

• Cumulative Load Count

• Cumulative Payload Total

• Distance

Not all vehicles will supply all data points

• Additional data points as defined by the ISO spec may be added based on industry and customer feedback.

• This API will return only machines with a telematic state of “active” which you can see in the Operations Center map page

The John Deere Precision Tech API endpoints use three-legged oAuth for authentication. OAuth is an open protocol, and we currently use OAuth2.

1. Create an Application on Developer.Deere.com

   When you create an application, your application will be assigned a Client Key and Client Secret. You will sign all API requests with these credentials.

2. Add a callback URL (Redirect URI) to your application

   On the OAuth Profile page of your application on Developer.Deere.com (found in the application Details section) you will need to define one or any number of Callback URLs (Redirect URI). Click the Add button to add more than one, and be sure to click Save at the bottom of the screen once you have completed entering all URLs.

   Note: If the callback URLs do not sync properly, your users will experience a 400 Bad Redirect error after authentication. Please contact us if you are receiving a 400 Bad Redirect for your callback URL in your testing. We will manually sync your callback with our OAuth provider if needed.

3. Call the OAuth 2 well-known URL

   Make a GET request to https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/.well-known/oauth-authorization-server. This URL contains the authorization and token endpoint, and the scopes required 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"
       ],
       "subject_types_supported": [
           "public"
       ],
       "scopes_supported": [
           "ag1",
           "ag2",
           "ag3",
           "eq1",
           "eq2",
           "files",
           "jobs",
           "org1",
           "org2",
           "openid",
           "profile",
           "email",
           "address",
           "phone",
           "offline_access"
       ],
       "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"
       ]
   }

4. 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, you will need to send a code response type parameter, along with OAuth scopes, client ID, state and redirect URI. The redirect_uri query parameter must be URL encoded (i.e. “https://example.client.com/callback” should be passed as “https%3A%2F%2Fexample.client.com%2Fcallback”)

   OAuth Scopes:

   The required scopes for the /Fleet endpoint are listed below.

   • eq1 - view equipment

   • offline_access - Request a Refresh Token

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

   

   Step 3 - The customer is redirected to John Deere sign-in page.

   

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

   

   Step 5 - The customer is presented with the scope allowance screen.

   

   Steps 6 & 7 - Scope acceptance is sent back to the OAuth server, and the customer is redirected back to the client application with authorization code.

   

5. Acquire an access token

   The client requests an access token from the token server by sending an authorization grant type authorization_code parameter, along with the authorization code, and a redirect URI. The authorization server authenticates the client and issues an access token and a refresh token (only if offline_access scope is requested). The access token will expire after 12 hours.

   

6. Post authorization redirect to enable organization access

   Once the client obtains a valid access token, there is an additional step required to allow users to enable organization 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 /fleet. If you see a ‘connections’ link in the response, your client has not received access to an organization. Note that a user may have access to multiple organizations but might not enable access for your client to all of them. In this multi-org scenario, you will only receive machine data for the organizations for which you have been granted access and the ‘connections’ link will continue to be included in the response until all organizations are enabled

      <Fleet
          xmlns="http://standards.iso.org/iso/15143/-3" version="2" snapshotTime="2017-03-24T13:02:38.191Z">
           <Links>
                 <rel>self</rel>
                 <href>https://sandboxapi.deere.com/aemp/Fleet/1</href>
           </Links>
           <Links>
                <rel>last</rel>
                 <href>https://sandboxapi.deere.com/aemp/Fleet/4</href>
           </Links>
           <Links>
                 <rel>next</rel>
                 <href>https://sandboxapi.com/aemp/Fleet/2</href>
           </Links>
      	<Links>
      	      <rel>connections</rel>
      	      <href>https://connections.deere.com/connections/deere-sld8shg8ee0o8ns8nhdh88hn/select-organizations</href>
      	</Links>
      </Fleet>
      

   2. If the ‘connections’ link is returned in the response, redirect the user into Operations Center using the URI provided. You can also provide a redirect_uri query parameter so the user will be redirected back to your application after the org 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 query parameter 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 re-directed 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 in Operations Center.

   5. Avoid getting into a redirect loop and only perform the connections redirect 1 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.

      Example Flow Diagram:

      

7. Setup periodic refresh token logic to acquire a new access token

   The client application will need to pass the refresh token to the authorization (token) server to obtain a new access token before the access token expires. 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 (back to steps 1&2). Note - The client will not be presented with the scope allowance screen again unless new scopes are requested in step 4.

   

Postman is a free desktop app, which you can use to test your John Deere API calls. We prefer using the Postman client in lieu of the test client for calling APIs while in Sandbox to see and follow REST API responses. 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).

2. Open Postman and to turn off the auto redirects, click on Settings at the top, as shown:




3. In the Authorization tab, there is a dropdown to select the type of authorization you’ll be using. Select OAuth 2 from the dropdown, as shown:



4. Select the Get New Access Token button.



5. Give your Token a Name.



6. Leave the Grant Type as Authorization Code.

7. The Callback URL for redirecting back to Postman after getting the Token is https://www.getpostman.com/oauth2/callback. Remember that if you will be using this Postman Callback URL, it will need to be synced with our OAuth client. See step 2 in this document for help in syncing this Callback URL with your application.

8. 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.

Enter the information in the appropriate boxes.



9. Navigate to Developer.Deere.com, login, and access your Application Profile in the "My Applications" section.

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. The Scope box should be filled out initially with eq1.

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

12. For Client Authorization, you can either send a Basic Auth request in the header, or client credentials in the request body.

13. Once the steps above are complete, press the Request Token button to proceed to the token verify screen.



14. Select the Use Token button to apply the token to your API call.

15. If you aren’t able to complete this process, or have any questions, please feel free to use the Support button in the top navigation of the page.

By default, collections are paginated. Each page of data contains 100 equipment values. The response will contain next, previous, and last links, which can be followed to view the entire response. The last page of data will not have a next link.

Page Item Limit

You cannot control the page size with this API.

Page Offset

You cannot control the page offset with this API.

Disabling Paging

You cannot disable paging for this API.