OAuth
MyJohnDeere API uses three-legged OAuth Security, an open protocol for authorization on the web. To use MyJohnDeere API, your application will need to use three-legged OAuth Security.
 
 
  1. Create an Application profile on developer.deere.com
    When you create the application profile, it will assign a Client Key and Client Secret to your app. You will sign all API requests with these credentials.
    Learn how to set up an app profile in the Get Started Guide.

  2. Retrieve URLs via the API Catalog
    The API Catalog lists available resources. It should be called every time the security context changes.
     
    John Deere's REST API uses hyperlinks to help clients navigate resources and discover possible actions or additional data. The starting place for clients is the API Catalog, which lists the available resources and should be retrieved every time the security context changes.
     
    For example, before obtaining an OAuth Token, clients should retrieve the API Catalog and reference the oauthRequestToken, oauthAuthorizeRequestToken, & oauthAccessToken relationships:
     
    GET https://apicert.soa-proxy.deere.com/platform/
    Accept: application/vnd.deere.axiom.v3+json
    Authorization: OAuth realm="",oauth_timestamp="1376256657", oauth_nonce="xgJFr4", oauth_consumer_key="com.deere.demo", oauth_version="1.0", oauth_signature_method="HMAC-SHA1", oauth_signature="TL054eykIBbVnSkbZqg2i4OrgLQ%3D"
     
    200 OK
    Date: Sun, 11 Aug 2013 21:30:56 GMT
    X-Deere-Elapsed-Ms: 15
    Transfer-Encoding: chunked
    Content-Language: en-US
    Content-Type: application/vnd.deere.axiom.v3+json;charset=UTF-8
    {
      "links":[
       {
        "rel":"oauthRequestToken",
        "uri":"https://apicert.soa-proxy.deere.com/platform/oauth/request_token"
       },
       {
        "rel":"oauthAuthorizeRequestToken",
        "uri":"https://my.deere.com/consentToUseOfData?oauth_token={token}"
       },
       {
        "rel":"oauthAccessToken",
        "uri":"https://apicert.soa-proxy.deere.com/platform/oauth/access_token"
       }
      ]
    }
     
    Obtaining the OAuth Token changes the security context, since requests are now made in the context of both the client application and the end user. After obtaining the OAuth Token, request the API Catalog again.
     
    GET https://apicert.soa-proxy.deere.com/platform/
    Accept: application/vnd.deere.axiom.v3+json
    Authorization: OAuth realm="",oauth_timestamp="1376259606",oauth_nonce="in6ytW", oauth_consumer_key="com.deere.demo", oauth_token="413fb748-6338-4a7d-832a-8789dc3aac67",oauth_version="1.0",oauth_signature_method="HMAC-SHA1", oauth_signature="nmyiYfI9722HgIzFsCesKduggHQ%3D"

    200 OK
    Date: Sun, 11 Aug 2013 22:20:07 GMT
    X-Deere-Elapsed-Ms: 16
    Transfer-Encoding: chunked
    Content-Language: en-US
    Content-Type: application/vnd.deere.axiom.v3+json;charset=UTF-8

    {
      "link" : [ {     "rel" : "files",
        "uri" : "https://apicert.soa-proxy.deere.com/platform/files"
      }, {
        "rel" : "organizations",
        "uri" : "https://apicert.soa-proxy.deere.com/platform/organizations"
      } ]
    }
     
    When using the API Catalog, client applications should only hard-code a single URI in their application: that of the API Catalog itself. All other URIs should be discovered using hyperlinks returned by the API, navigating using the link relationships (rel).
     
    John Deere will rely on this style of implementation and may change URIs other than the API Catalog without notice.

  3. Request a Request Token (passing Client key and Client secret).
    Sign request with your app ID and secret. Pass an oauth_callback parameter in the Authorization header. If you don't have a callback URI, pass oob instead. Passing oob instead of a callback URI will make the token and verifier appear on the screen. The user will then have to copy that information into the app.

  4. Redirects user to authentication URI (passing token).

    Verifier Code
    A callback URI can be used to remove the human interaction with the Verifier Code. Learn more about Callback URIs.

  5. Trade Request Token for Access Token.

    Notes on Access Tokens:
    • They are valid up to one year. You will have to request another token if the one you have is invalidated.
    • One token is specified to one client and one resource owner.
    • You should store the access token and secret for each user, so that the user does not need to authorize every request made by the client.

View OAuth sample application.
 
Callback URIs
After the user (resource owner) authorizes the Request Token, MyJohnDeere will redirect the user's browser to the callback URI provided when the client requested the Request Token. The Request Token and Token Verifier will be appended to the callback.
 
For example, if the provided callback is https://example.deere.com/my-great-app and the token is pMhq7hhTpeXV31hK2gz1, the browser will be redirected to https://example.deere.com/my-great-app?oauth_token=pMhq7hhTpeXV31hK2gz1&oauth_verifier=hu5ZN3.
 
The client application should process the oauth_token and oauth_verifier parameters and exchange them for an Access Token (which is then used for subsequent requests on behalf of this user).
 
These steps work particularly well for web-based clients. Other clients have some other options.
  1. Clients can request an Out-of-Band verifier exchange by passing OOB as the callback URI. In this case, MyJohnDeere will display the verifier to the user instead of redirecting their browser.
  2. Clients can register a custom protocol handler with their operating system, and use the custom protocol in their callback URI.
    For example, Acme Company might register the acme: protocol with the OS and include the callback URI acme:myGreatApp. When the browser redirects to acme:myGreatApp?oauth_token={token}&oauth_verifier={verifier}, the OS will hand the URI to the application registered to handle the acme: protocol.
One method to be avoided for capturing the verifier is to embed a web browser into the client application and capture its events. John Deere encourages our users to only enter their credentials into John Deere tools and websites. Given this expectation, users will be uncomfortable entering their credentials into third-party applications. As a result, this method is not allowed.