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)

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; the values for the key and password can be found on the User details page in the UI. Either of these values can be used in the REST URLs for authentication
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 that the cookie is set for. 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=aspera 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=Aspera123_' 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=`.

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; the values for the key and password can be found on the User details page in the UI. Either of these values can be used in the REST URLs for authentication

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 that the cookie is set for. 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=aspera

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=Aspera123_'

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 withapi_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"/>