API authentication guide 4.1.2 and earlier

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: IBM Aspera supports secure authentication such as HTTP basic authentication, API keys, or a scrambled password. Inline user name and password credentials in commands or the UI are not supported.

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

API calls authentication methods

Authentication Model Description

HTTP basic authentication (most secure)

Authentication Model	Description
HTTP basic authentication (most secure)	This is 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: Basic access_token`
API key or scrambled password	They 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: At the top-right of the Orchestrator UI, click the admin dropdown arrow and click Accounts. In the far-left navigation, click Users. In the Users list, click the name for the desired user. The Modify User Information section appears at the topic of the page. 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 `Orchestrator_IP_address` 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://Orchestrator_IP_address/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=`.

This is 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: Basic access_token

API key or scrambled password

They 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:

At the top-right of the Orchestrator UI, click the admin dropdown arrow and click Accounts.
In the far-left navigation, click Users.
In the Users list, click the name for the desired user. The Modify User Information section appears at the topic of the page.
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 Orchestrator_IP_address 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://Orchestrator_IP_address/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://Orchestrator_IP_address/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"/>