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 clear. 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 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/login=admin?password=aspera 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.

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 clear. 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 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/login=admin?password=aspera

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.

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 this URL:

http://localhost/aspera/orchestrator/users/logoff/xml

Sample XML response for logoff:

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