OAuth authentication endpoint

Path: token

Method:POST

Description:The API is based on OAuth authentication. At the time of writing the only authentication grant supported is Client Crendtials. The following scopes are supported:

api - this will require an api licence
view - If this is the only scope specified a licence count is not required, however, no modifications to Jim2 objects will be allowed.

If a scope is not specified the default is 'all' and full user licence will be required. The refresh token has an expiry time of 20 minutes, and can be extended by requesting a new access token. Note that while the refresh token is valid a licenced user session is held by Jim2Server. Authentication will also fail if there are no available licences (unless only scope view is specified). Credentials may be passed within the request body (ie specifying) using the client_id and client_secret parameters) or using HTTP Basic BASIC authentication scheme (ie. specifying the user credentials in the Authorization HTTP header).
If the caller wants to release a licence prior to the token timing out the calller will need to logoff. See documentation for the logoff endpoint.

Example C# OAuth client_credentials call


            WebRequest req = WebRequest.Create( "http://localhost:80/Jim_Test/token" );
            req.Method = "POST";

            // the user:password string for HTTP Basic authorisation 
            // - user is the OAuth clientid (configured in the client id to use initial mapping) 
            // - password is the OAuth secret (the secret is the user cardfile's password)
            string sTemp = "TestClientId:password";
            string sEncoded;
            using (System.IO.MemoryStream ms = new System.IO.MemoryStream())
            {
                System.IO.StreamWriter writer = new System.IO.StreamWriter( ms );
                writer.Write( sTemp );
                writer.Flush();
                sEncoded = System.Convert.ToBase64String( ms.ToArray() );
            }
            req.Headers.Add( "Authorization", "Basic " + sEncoded );

            // the OAuth client credentials grant requires a form encoded request
            // NB: you can specify the client_id and client_secret in the form body as an alternative
            // to using the HTTP Authorization header as per above
            req.ContentType = "application/x-www-form-urlencoded";

            using (var str = req.GetRequestStream())
            {
                using (var writer = new System.IO.StreamWriter( str ))
                {
                    writer.Write( "grant_type=client_credentials" );
                    // per comments above, readonly and no licence count taken
                    writer.Write( "&scope=view" );
                }
            }

            /* 
               NOTE: 
               we recommend using the System.Net.Http.FormUrlEncodedContent class to build
               the request content if you are using the System.Net.Http.HttpClient class
               to manage your web api calls.

              Dictionary values = new Dictionary(CustomFormValues);
              values.Add( "client_id", m_sClient_id );
              values.Add( "client_secret", m_sSecret );
              if (!string.IsNullOrEmpty( scopes ))
              {
                  values.Add( "scope", scopes );
              }
              values.Add( "grant_type", "client_credentials" );

              HttpContent content = new FormUrlEncodedContent( values );
              var resp = await httpClient.PostAsync( TokenUrl, content );
            */

            var resp = req.GetResponse();
            using (var strResp = resp.GetResponseStream())
            {
                using (var reader = new System.IO.StreamReader( strResp ))
                {
                    string sResponse = reader.ReadToEnd();
                    // parse the tokens from the JSON response
                    RecvAccessToken rat = Newtonsoft.Json.JsonConvert.DeserializeObject( sResponse );
                    sAccessToken = rat.access_token;
                    sRefreshToken = rat.refresh_token;
                    // you also look at rat.expires_in so you can cache the token appropriately, or logoff
                }
            }