To interact with BMC Atrium Orchestrator through the REST API, you must log in and obtain an authentication token. Save the authentication token that you receive in the response to your logon request and include it in the header of each subsequent request during the session. The token is valid as long as your session remains active. The session time is defined by Atrium Single Sign-On parameters (see Managing the server configuration). If your session times out due to inactivity, you must log on again and obtain a new token.

This topic includes the following sections:

To log in and obtain an authentication token

1. Send the following HTTP request, replacing <yourUsername> and <yourPassword> with your user name and password:

   POST /rest/login
   Host: atrium-orchestrator-url
   { "username" : "<yourUsername>", "password" : "<yourPassword>"
   }

   The response for a successful login looks like the following:

   {"login":"true"}

2. From the response, save the text string returned in the Authentication-Token: header. That text string is your authentication token.
   For example, in the following response, you would save the following:
   AQIC5wM2LY4SfcyLDAZyTRIKrqijnrmwYBF5LyyWnRWj0Kw.*AAJTSQACMDIAAlNLAAoxODI3MTY0MzQ0AAJTMQACMDE.*

   HTTP/1.1 200 OK
   Date: Wed, 11 Jan 2014 13:23:04 GMT
   Authentication-Token: AQIC5wM2LY4SfcyLDAZyTRIKrqijnrmwYBF5LyyWnRWj0Kw.*AAJTSQACMDIAAlNLAAoxODI3MTY0MzQ0AAJTMQACMDE.*
   Content-Type: application/json; charset=ISO-8859-1
   Content-Length: 2
   Server: Jetty(6.1.9) 

3. In each subsequent request, include the authentication token request header, as shown in the following example: 

   POST /rest/process/execute
   Host: atrium-orchestrator-url
   Authentication-Token: AQIC5wM2LY4SfcyLDAZyTRIKrqijnrmwYBF5LyyWnRWj0Kw.*AAJTSQACMDIAAlNLAAoxODI3MTY0MzQ0AAJTMQACMDE.*

Example: Logging into the REST API server using the Firefox REST plugin

To logout from the API server 

Send the following HTTP request with the authentication-token:

POST /rest/logout
Host: atrium-orchestrator-url
Authentication-Token: AQIC5wM2LY4SfcyLDAZyTRIKrqijnrmwYBF5LyyWnRWj0Kw.*AAJTSQACMDIAAlNLAAoxODI3MTY0MzQ0AAJTMQACMDE.*

Video demonstration

The following BMC Communities video (7:30) is part one of a two-part series on using REST to execute workflows. This video demonstrates how to log into an API server, generate an authentication code, and use the code to get process details, execute a workflow (process), retrieve a list of active modules, and get a job's status. It covers the login and logout calls.

The second part of the video demonstrates how to use the HTTP adapter to perform the same tasks and is available in the BMC Atrium Orchestrator Content wiki's HTTP adapter section.

Login example

Logout example

HTTP request and response headers