This documentation supports the 9.0 version of Remedy Action Request System.

To view the latest version, select the version from the Product version menu.

Login information

All REST API calls must be authenticated. Instead of passing the full credentials on every REST API call, REST uses a token. The token is valid for a configurable amount of time and acts like a temporary password. 

Note

For more information on Token based authentication, watch the video on YouTube at  Example authentication.

This section provides the following topics:

Issuing and sending the token

  1. The client creates a POST call and passes the user name, password, and authString in the body using the /x-www-form-urlencoded content type.

    POST /api/jwt/login HTTP/1.1
    host: www.example.com
    
    username=SomeUser&password=mysecret&authString=authenticationstring
  2. The AR System server performs the normal authentication mechanisms to validate the credentials. If the credentials are valid, the AR Server generates a JSON Web Token (JWT).

    // comments not actually included, added for clarity
    {
        // the username
        "sub" : "SomeUser",
        // the Server-Connect-Name of the AR Server who issued the token
        "iss" : "www.example.com",
        // the UNIX time when the token was issued
        "iat" : 1408774310,
        // 2 minutes before "iat", to account for clock skew between servers
        "nbf" : 1408777790,
        // the UNIX time when the token expires, the duration being a configurable value (probably between 1 minute and 12 hours)
        "exp" : 1408777910,
        // a custom claim, the cache ID
        "_cacheId" : 13
    }

    Note

    If the user provides a blank password, the AR System server does not attempt to cross-reference the password.

  3. The JWT is signed and base64 encoded string, and is sent back as a response body to the HTTP request.

    HTTP/1.1 200 OK
    
    eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
  4. The client receives the token and uses it in all subsequent REST API calls through the Authorization header using the AR-JWT schema.

    GET /api/arsys/v1/entry/SomeForm HTTP/1.1
    Authorization: AR-JWT eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

To create the token

All REST requests must be authenticated. REST uses token based authentication.

DescriptionCreates a new token.
URL qualifier/api/jwt/login
MethodPOST
Headers
HeaderValue
username<username>
password<password>
authString<authentication string>
Content-typeapplication/x-www-form-urlencoded
ReturnsAn encoded string in the response body referred as TOKEN.

    This example provides information to create a token.

    Request URL

    POST http://localhost:8008/api/jwt/login

    Request headers

    Content-Length: 32
    Content-Type: application/x-www-form-urlencoded
    
    username=Allen&password=password
    

    Response body

    HTTP/1.1 200 OK
    Date: Wed, 03 Dec 2014 23:39:41 GMT
    Content-Type: text/plain
    Server: Jetty(8.1.15.v20140411)
    
    eyJhbGciOiJIUzI1NiJ9.
    eyJleHAiOjE0MTc2NTM1ODgsInN1YiI6IkFsbGVuIiwibmJmIjoxNDE3NjQ5ODY4LCJpc3MiOi
    JXLUNTRUlFUk9FLTI5LmFkcHJvZC5ibWMuY29tIiwianRpIjoiSURHQUFCRFVDMllHSUFONkJGUTJBQUFFUEZBNVFXIiwiX2NhY2hlSWQiOjQ3LCJpYXQiOjE0MTc2NDk5ODh9.
    V4LGLcEdwD8V_I4rzoWYYSZmEMA82LBB_lEfz4Xnz9Y
    

    The following is a sample code snippet for creating the token.

    package com.example;
    
    import java.nio.charset.StandardCharsets;
    import java.util.ArrayList;
    import java.util.List;
    
    import org.apache.http.HttpEntity;
    import org.apache.http.NameValuePair;
    import org.apache.http.client.entity.UrlEncodedFormEntity;
    import org.apache.http.client.methods.CloseableHttpResponse;
    import org.apache.http.client.methods.HttpPost;
    import org.apache.http.impl.client.CloseableHttpClient;
    import org.apache.http.impl.client.HttpClients;
    import org.apache.http.message.BasicNameValuePair;
    import org.apache.http.util.EntityUtils;
    
    public class Login {
    
        public static void main(String[] args) throws Exception {
            // start HTTP POST to get a token
            CloseableHttpClient httpClient = HttpClients.createDefault();
            HttpPost httpPost = new HttpPost("http://localhost:8008/api/jwt/login");
    
            // send the username and password
            List<NameValuePair> nvps = new ArrayList<>();
            nvps.add(new BasicNameValuePair("username", "Allen"));
            nvps.add(new BasicNameValuePair("password", "password"));
            httpPost.setEntity(new UrlEncodedFormEntity(nvps));
    
            // make the call and print the token
            try (CloseableHttpResponse response = httpClient.execute(httpPost)) {
                HttpEntity entity = response.getEntity();
                String token = EntityUtils.toString(entity, StandardCharsets.UTF_8);
                System.out.println(token);
            }
        }
    
    }

    To release the token

    Description Releases the token.
    URL qualifier/api/jwt/logout
    MethodPOST
    Headers
    HeaderValue
    Authorizationtoken

      This example provides information to release a token.

      Request URL

      POST http://localhost:8008/api/jwt/logout

      Request header

      Authorization: AR-JWT eyJhbGciOiJIUzI1NiJ9.
      eyJleHAiOjE0MTc2NTM1ODgsInN1YiI6IkFsbGVuIiwibmJmIjoxNDE3NjQ5ODY4LCJpc3MiOi
      JXLUNTRUlFUk9FLTI5LmFkcHJvZC5ibWMuY29tIiwianRpI
      joiSURHQUFCRFVDMllHSUFONkJGUTJBQUFFUEZBNVFXIiwiX2NhY2hlSWQiOjQ3LCJpYXQiOjE0MTc2NDk5ODh9.
      V4LGLcEdwD8V_I4rzoWYYSZmEMA82LBB_lEfz4Xnz9Y

      Response body

      HTTP/1.1 204 No Content
      Date: Wed, 03 Dec 2014 23:46:03 GMT
      Server: Jetty(8.1.15.v20140411)
      

      The following is a sample code snippet for releasing the token.

      package com.example;
      
      import org.apache.http.StatusLine;
      import org.apache.http.client.methods.CloseableHttpResponse;
      import org.apache.http.client.methods.HttpPost;
      import org.apache.http.impl.client.CloseableHttpClient;
      import org.apache.http.impl.client.HttpClients;
      
      public class Logout {
      
          public static void main(String[] args) throws Exception {
              String token = args[0];
      
              // start HTTP POST to logout and invalidate the token
              CloseableHttpClient httpClient = HttpClients.createDefault();
              HttpPost httpPost = new HttpPost("http://localhost:8008/api/jwt/logout");
      
              // add the token to the header
              httpPost.addHeader("Authorization", "AR-JWT " + token);
      
              // make the call and print the status
              try (CloseableHttpResponse response = httpClient.execute(httpPost)) {
                  StatusLine status = response.getStatusLine();
                  System.out.println(status);
              }
          }
      
      }

      Related topics

      Was this page helpful? Yes No Submitting... Thank you

      Comments

      1. Kumar Lama

        I can not make HTTPS API client requests and gives me an error "...Host does not match the certificate subject provided  by the peer..."

        How would I go about handling (not skipping) the SSL certification via JAVA API client ?

        Nov 30, 2016 01:28
        1. Christopher Seieroe

          The error sounds like the certificate is for "foo.example.com" but you're using "bar.example.com" when making the REST API calls. Make sure you're connecting with the same hostname the certificate was generated for.

          Nov 30, 2016 01:35
      2. Joseph Dobie

        Hi Chris/BMC,

        I've looked everywhere for the following information but am coming up blank. Is there a way to pass basic authorization in each request instead of generating an authorization token that expires?

        Jan 24, 2017 12:09
        1. Poonam Morti

          Hi Joseph,

          I have checked this with the SME, token is the only way of sending authorization information with each request.

          Thanks,

          Poonam

           

          Feb 07, 2017 03:14
      3. Ashish Vaishno

        Hello,


        How can I fix the below error

        User is currently connected from another machine or incompatible session.


        I am only logged in from one PC/Session. 


        Regards

        Ashish

        Apr 06, 2018 04:11
      4. Benjamin Bowie

        How do you utilize AD Credentials?

        Jun 28, 2018 12:04
      5. Onkar Telkikar

        Hello Benjamin,

        I will discuss your comment with the SME and will get back to you shortly.

        Thanks,

        Onkar

        Jun 29, 2018 02:05
        1. Onkar Telkikar

          Hello Benjamin,

          For AD credentials, if LDAP is configured properly with the AR Server, an AD user will get authorized as usual. This process also works for the RPC APIs.

          Regards,
          Onkar

          Oct 24, 2018 08:22
      6. Benjamin Bowie

        So--- 

        Request headers

        Content-Length: 32
        Content-Type: application/x-www-form-urlencoded
         
        username=Allen&password=password

        for AD login ?-

        username=DOMAIN\USER&password=password

        Oct 24, 2018 08:40
      7. Onkar Telkikar

        Hello Benjamin,

        Please use the same login name here that you use while logging on to the Mid Tier.

        Regards,
        Onkar

        Nov 01, 2018 03:59
      8. Benjamin Bowie

        Using RSSO to login to Mid Tier - so it's utilizing AD FS to authenticate. (I presume gathering a token somewhere? RSSO documentation is lacking as well)


        Looking to utilizing AD / LDAP via REST to authenticate. 


        Documentation above is limited to Remedy based authentication?

        Nov 01, 2018 08:23
        1. Onkar Telkikar

          Hello Benjamin,

          The documentation is not limited to Remedy-based authentication. You can use external authentication as well.

          Please see the following topic for more information:
          AR System external authentication

          Once you configure external authentication, it will be automatically applicable to REST API as well.

          Regards,
          Onkar

          Nov 26, 2018 04:18
      9. Lonnie Murray

        Is there a way to use impersonation like you can in the other APIs so that that system fields record the updates as being done by another specified user?

        Apr 25, 2019 02:17
        1. Anagha Deshpande

          Hello Lonnie,

          We are working on your query. We will respond soon.

          Regards,

          Anagha


          Apr 25, 2019 11:22
          1. Anagha Deshpande

            Hello Lonnie,

            Currently, BMC does not support impersonation for REST API. 

            Regards,

            Anagha

            Apr 29, 2019 04:28
      10. Bhumika Acharya

        While calling /api/jwt/login it returns below :

        HTTP ERROR 500

        Problem accessing /api/jwt/login. Reason:

                <pre>    Request failed.</pre>
            </p>
        </body>
        

        Any suggestions ?

        Oct 02, 2019 02:39
        1. Onkar Telkikar

          Hello Bhumika,

          This is an internal server error. Please ensure that you are using the correct headers and request body.

          Regards,
          Onkar


          Oct 18, 2019 05:36
      11. Aditya Singh

        Does BMC OAuth support Introspect endpoint as per RFC7662. E.g link --> https://www.oauth.com/oauth2-servers/token-introspection-endpoint/

        Oct 23, 2019 11:21
        1. Onkar Telkikar

          Hello Aditya,

          We are working on your query. Will respond shortly.

          Thanks,
          Onkar

          Oct 24, 2019 04:33