This documentation supports the 20.02 version of Remedy Action Request (AR) System.

To view an earlier version, select the version from the Product version menu.


Access and authentication for the REST API

Requests to all endpoints in the REST API must be on behalf of a Remedy AR System user. Before processing a request, the API authenticates the request to determine the user. The API uses the  OAuth 2.0  protocol for this authentication, and the process is based on tokens as described below.

After successful authentication, a permission check decides if the user is allowed to perform the requested action. This check uses the existing permissions.

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.

Authentication workflow:

TaskActionReference
1Create a POST call for issuing and sending tokenApplication credential requirements
2Create a token for authenticationTo generate a token from the /jwt/login endpoint
3Release the tokenTo release a token from the /jwt/logout endpoint

The following video (4:23) gives an overview of token-based authentication for every API call.

 https://youtu.be/xue9Gx-dbEA

This video was recorded using the earlier version of BMC Remedy AR System but is valid for BMC Remedy AR System 9.1 and later versions.

Application credential requirements

The client must create a POST call and pass the user name, password, and authString in the Request headers using the /x-www-form-urlencoded content type.

The AR System server then 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 one hour. You can use a single token across multiple AR servers that are in the same server group.

Note

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

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

The client receives the token and uses it in all subsequent REST API calls through the Authorization header using the AR-JWT schema.

For more information, see Overview of the REST API.

Connections by HTTP and HTTPS

By default, access to the REST API is over HTTPS only and HTTP access is not permitted. An attempt to access any of the API endpoints (with the exception of /api/about and /api/version) over HTTP will result in a 403 Forbidden error.

curl -i http://appliance/api/about
 
HTTP/1.1 403 Forbidden
{
    "message"   : "Access forbidden",
    "code"      : 403,
    "transient" : false
}

On a new server, you must configure HTTPS before attempting to access the API (including submitting requests by using the Swagger UI).

On the HTTPS configuration page, you can enable API access over HTTP, but this is not recommended in production and should only be used for testing purposes. API requests contain your Authentication token in an HTTP header, and this is passed in plain text when you use HTTP.

For the same reason, if the appliance is configured to redirect HTTP requests to HTTPS, API access over HTTP cannot be enabled. This is to avoid the illusion of security, where the initial request to the API is transmitted in plain text and contains either your API token or contains a username and password combination.

For more information, see Configuring the REST API by using SSL certificates .

Authentication scheme

This API follows the OAuth 2.0 specification with API tokens. An authentication token is an opaque string. A token is associated with one Remedy AR System user, which could be a local or LDAP user. Some tokens include an expiry time, after which they are no longer valid, while others are permanent and never expire. In both cases, the token should be protected as securely as a password.

For information about how to authenticate the AR REST API, see Using the REST API with Swagger.

To generate a token from the /jwt/login endpoint

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

DescriptionCreates a new token.
URL qualifier/api/jwt/login
MethodPOST
Headers
HeaderValue
authString<authentication string>
Content-typeapplication/x-www-form-urlencoded
Body
KeyValue
username<username>
password<password>
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
    

    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 a token from the /jwt/logout endpoint

    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)
      

      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);
              }
          }
      
      }

      If you log in with your credentials on one computer and you try to log in from a different computer with the same credentials, you get a 9093 error. For more information about a 9093 error, see Error messages 8900 to 9100.

      Required and optional headers

      Following are the required and optional headers for REST APIs.

      HeaderValue
      AuthorizationToken
      (Optional) X-AR-Client-TypeClient Type ID
      (Optional) X-AR-RPC-QueueRPC queue to which the client calls are routed
      (Optional) X-AR-Timeout

      Timeout (in seconds) for REST request

      Default value —120 seconds

      (Optional) X-AR-TR-Core-IdThe core ID in a trace ID
      (Optional) X-AR-TR-CounterThe counter in a trace ID
      (Optional) X-AR-Trace-IdThe complete trace ID
      (Optional) X-AR-TR-Is-Counter-LockedThe lock counter

      Related topics

      Integrating AR System forms with a third-party application by using the REST API

      Endpoints in AR REST API

      Enabling OAuth authorization for Remedy AR System REST APIs

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

      Comments