Authentication

API calls require proper authentication and have the same authorization requirements as those applied to direct access to Orchestrator through its web-based user interface.

Note: Aspera endorses secure methods for logging in, such as HTTP basic authentication, an API key, or a scrambled password. Aspera does not endorse the method of entering a user name and password inline or in the UI.

There are a number of ways to authenticate API calls; these are described in the table below.

Authentication Model Description
HTTP basic authentication (most secure) HTTP basic authentication is supported and is recommended to developers as the primary authentication model. The advantage of this method is that the credentials are within each request but they are encoded versus being in plain text. The username and password are combined into a string, "username:password", then they are Base64-encoded and put in the HTTP Authorization header. For example:
Authorization:BasicQWxhZGRpbjpvcGVuIHNlc2FtZQ==
API key or scrambled password An API key and a scrambled password are generated for each Orchestrator user; either of these values can be used in the REST URLs for authentication. For example:
https://orchestrator3.asperademo.com/aspera/orchestrator/api/initiate/124.json?login=admin&api_key=ghawQesLH2OnnLxpHNAeCwzzm81071841979945
https://orchestrator3.asperademo.com/aspera/orchestrator/api/initiate/124.json?login=admin&password=_P__Agx825xg1h10p0h7jzn04b03748jhkoi773850547
To obtain the values for the API key or password, do the following:
  1. At the top-right of the Orchestrator UI, click the admin dropdown arrow and click Accounts.
  2. In the far-left navigation, click Users.
  3. In the Users list, click the name for the desired user. The Modify User Information section appears at the topic of the page.
  4. For an API key, copy the string that is in the API Key field. For a password, click the Generate Scrambled Password button and copy the string that appears.
Application cookie

This can be used if the client is able to use cookies to maintain state information. Once the authentication is made, it will not be necessary to set the credentials again for additional calls.

The user obtains the cookie from the authentication call by supplying a username and password. If this is a particular process that will only ask for a cookie once, then the logoff for that process will also need a cookie to correctly log off the user for which the cookie is set. The cookie should be supplied in the HTTP header.

The host name in the URLs is defined as localhost in this document to represent the IP address or the fully qualified host name of your Orchestrator node.

Below is an example of a cookie-style request:
http://localhost/aspera/orchestrator/api/authenticate/admin?password=_P__Agx825xg1h10p0h7jzn04b03748jhkoi773850547
The following curl requests are used to obtain an authentication cookie.
  • Get the cookie and write to file:
    curl -v  -b orch.cookies -c orch.cookies -k -X GET 'https://10.0.142.14/aspera/orchestrator/workflow_reporter/authenticate/admin?password=_P__Agx825xg1h10p0h7jzn04b03748jhkoi773850547'
  • Expose the cookie for API calls:
    curl -v  -b orch.cookies -c orch.cookies -k -X GET 'https://10.0.142.14/aspera/orchestrator/workflow_reporter/workflows_list/0'
After a successful authentication, the next URL (for example, one used to initiate a work order) can be called without providing the login and password parameters; this continues until the user is logged off.
Note: To enable CORS on an Apache server, replace the password= in the cookie request with api_key=.

Sample XML response for success:

<?xml version="1.0"?\>
<user time="2011-10-20 17:47:05 UTC" action="authenticate" id="1" login="admin"/>

Sample XML response for a bad password case:

<?xml version="1.0"?> 
<error time="2011-10-20 17:45:39 UTC" action="status" id="0">#<RuntimeError: 
Authentication failed></error>

Sample XML response for case in which the user does not exist:

<?xml version="1.0"?> 
<error time="2011-10-20 17:48:09 UTC" action="status" id="0">#<RuntimeError: 
Authentication failed></error>
To log off, use the following URL:
http://localhost/aspera/orchestrator/users/logoff/xml
Note: You must include the cookie you obtained when you logged in.

Sample XML response for logoff:

<?xml version="1.0"?> 
<user time="2012-01-25 06:38:22 UTC" action="logoff" id="1" login="admin"/>