This documentation supports the 9.1 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 video is recorded using the earlier version of BMC Remedy AR System and is valid for BMC Remedy AR System 9.1 and later versions.

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 Request headers 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).
    You can attempt a REST API call if you have a token. A single JWT token is valid for an hour. You can use a single token across multiple AR servers that are in the same server group.

    // 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. The user who is using the REST API fails the token authentication but can keep using the REST API even after the token expires.

  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.

Description Creates a new token.
URL qualifier /api/jwt/login
Method POST
Headers
Header Value
authString <authentication string>
Content-type application/x-www-form-urlencoded
Body
Key Value
username <username>
password <password>
Returns An 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
    Method POST
    Headers
    Header Value
    Authorization token

      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. David Fiel

        In "Issuing and sending the token," it would be better to say "Add a header to the POST request setting Content-Type to application/x-www-form-urlencoded."

         

        Jul 06, 2016 01:09
      2. Jim Coryat

        Is it possible to decode the response token to identify what the expiration time is?  This would allow my to only get a new token when the old one has expired without having to intimately know what the expiration period is set to on the remedy server.

        Jul 17, 2017 01:51
        1. Anagha Deshpande

          Hello Jim,

          I will check this with the SME and will write back to you.

          Regards,

          Anagha 

          Jul 17, 2017 10:23
          1. Anagha Deshpande

            Hello Jim,

            You cannot decode the response token, You need to get a new token before the token expires. 

            Regards,

            Anagha

             

            Jul 18, 2017 12:34
            1. Jim Coryat

              Just found out through a colleague that your SME is incorrect or purposely withholding information. The JWT is a standards based format (RFC 7519) https://tools.ietf.org/html/rfc7519 that is able to be decoded. It does not give you credentials etc. but it does decode the claims information about the token which was what I was after.

              The link is http://jwt.io

              The RFC standards states the following claims are specific to the expiration: "exp" = Expiration Time "nbf" = Not before

              Both these values are in ticks format (Unix epoch) as Remedy dates are. Hopefully this is useful to others asking the same question.

              Sep 07, 2018 09:20
              1. Anagha Deshpande

                Hello Jim,

                Thanks for bringing this to our notice. We are cross-checking on this.

                Regards,

                Anagha

                Sep 09, 2018 09:37
                1. Onkar Telkikar

                  Hello Jim,

                  Please note that BMC does not recommend decoding and using the embedded information from the JWT token.

                  Regards,
                  Onkar

                  Oct 24, 2018 08:28
                  1. Jim Coryat

                    Actually no great surprise there. Just confirms I hit the nail on the head.

                    Oct 24, 2018 09:33
      3. Dave Dewolf

        When releasing the token via the above information I am getting the correct 204 message but the user is not logged out of Remedy v9.1. Should that be the expected behavior?

        Jan 24, 2018 09:47
        1. Anagha Deshpande

          Hello Dave,

          I will check your query with the SME and will write back to you.

          Regards,

          Anagha

          Jan 24, 2018 10:20
          1. Anagha Deshpande

            Hello Dave,

            Apologies for responding late.

            We have validated this case. When you log out from the REST API, the token is released and is no longer valid. No more REST calls are allowed.
            If you have logged in from other Remedy clients, for example, mid tier, you can still access Remedy.

            Regards,

            Anagha

            Jun 12, 2018 10:54
      4. Josue Araujo

        How long is the authentication token valid?

        Apr 18, 2018 04:50
        1. Anagha Deshpande

          Hello Josue,

          I will check your query with the SME and will respond to you.

          Regards,

          Anagha

          Apr 18, 2018 10:05
          1. Priyanka Gupta

            Any response on this. I really need to know how long these tokens are valid until. I am getting an Unauthorized message after a certain amount of time. Not sure if that is due to number of calls being made per minute or if the validity of JWT has expired?

            May 23, 2018 04:01
        1. Anagha Deshpande

          Hello Josue,

          By default, the authentication token is valid for one hour. You can control this value by using the AR_SERVER_INFO_EA_SYNC_TIMEOUT parameter.

          Regards,

          Anagha

          Jun 12, 2018 10:56
          1. Simon De'ath

            Hi Anagha - Can you advise where this parameter is set? Thanks

            Jul 26, 2018 07:17
            1. Kaushal Pandya

              This parameter can be found in ar.cfg/ar.conf file on AR Server. https://docs.bmc.com/docs/ars91/en/argetserverinfo-609070920.html#ARGetServerInfo-sync_timeout

              Oct 01, 2018 03:37
      5. Dongsheng Zhang

        How to ignore the Authentication? Our company has own OneAPI platform, the API will be integrated with OneAPI platform, the consumer will be authenticated via API-Key which provided by OneAPI platform, and create entry directly. The microgateway is installed on web tier, consumer will access to gateway then REST API.

        Nov 28, 2018 04:27
        1. Anagha Deshpande

          Hello Dongsheng,

          Apologies for the late response.

          You cannot ignore the AR REST API authentication.

          Regards,

          Anagha

          Apr 22, 2019 04:41