Registering an API client

Edit online

For developers building clients, this topic contains the procedure to register your client for use of the Aspera on Cloud API.

See also IBM Aspera Developer Center.

Note: IBM Aspera provides a full suite of APIs to support customer integrations. Always use the Aspera APIs to build integrations. Do not build integrations using application URLs or other methods.

Registering a client that uses browser-based authentication

Edit online

If your client uses browser-based (authorization code grant flow) authentication, you can configure whether or not the browser prompts users of your client explicitly to grant your client access Aspera on Cloud. If not, your users are not prompted and permission is assumed.

To register your API client for browser-based authentication, do the following:

  1. In the Admin application, select Integrations > API clients.
  2. Click Create new.
  3. Enter the name of the client; this name is for your reference only and does not need to match the actual name of your app.
  4. Select the check box labeled Users must explicitly allow the client to access IBM Aspera on Cloud if you want Aspera on Cloud to present a dialog box to your application users asking them to allow your client application to access Aspera on Cloud for contacts and other resources.
  5. In the Redirect URIs field, enter the redirect URIs for your application, separating multiple URIs with commas.
    A redirect URI (protocol-host-port) is an absolute URI invoked after the authorization flow to return the user to the client app. For more information, refer to the Aspera on Cloud API documentation on the IBM API Hub.
  6. In the Origins field, enter the origins for your app, separating multiple origins with commas.

    An origin is the URI or protocol-host-port of the client app initial login page, from which the user must arrive to the authentication flow.

  7. Click Save.

Result: Aspera on Cloud completes registration of your client app, then generates and displays the client ID and secret you need to access the API.

Registering a client that uses JWT authentication

Edit online

Aspera on Cloud supports the JSON Web Token-based OAuth 2.0 grant type (a grant type specifies how a client interacts with an identity server to authorize access to protected resources) to enable client applications to use the API without a user having to log in from a web browser.

A JSON web token includes, among other things, a user ID (the email of the user to authenticate), and is signed with a valid private key. In response to a valid JWT request submitted to the API, AoC returns an access token for the user identified in the JWT token request. Further requests to the API must include this access token to be valid. Requests as a specific user are permitted according to that user's permissions and access in the Aspera on Cloud application.

Note: JWT authentication for a given Aspera on Cloud user requires either a user-specific public/private key pair, or a client-level 'global' (not user-specific) public/private key pair, depending on your configuration. Creating a public/private key pair is a simple, standardized process; search the web for a procedure appropriate to your platform.

Retrieving admin tokens

Edit online

You can enable users of this client who are organization administrators to retrieve admin-scoped node access tokens from the API. Such a token provides the user with admin privileges on the node itself. See the procedure below.

Users and keys

Edit online

You must configure which users can access the API using your client, and which key – either a user-specific key or a global key – each user can submit to retrieve an access token.

There are two configuration parameters for users and keys.

  • Users:
    • All users: All users in the Aspera on Cloud organization are eligible to retrieve an access token.
    • Only listed users: Only users you list are eligible to receive an access token.
  • Keys:
    • User-specific keys: The JWT must be signed with the specified user's own private key.
    • User-specific keys and global key: The JWT can be signed with the specified user's own private key or with the global private key. (The global key is tied to the client just as the user-specific key is, but the global key can be applied to all users.)
Note: Any user accessing the Files API using the JWT method must have their public key listed in their Aspera on Cloud user record. The user can enter their own public key using the Account settings option of the User menu, or the organization administrator can enter the user's public key in the individual user's record.
Important: API clients with a global key can retrieve access tokens for and act as any listed user. Use global keys according to local site security practice.

The Users and Keys parameters interact with each other to enable various valid combinations, as the table below indicates:

User-Specific Key User-Specific Key and Global Key
All Users

API clients can request access as any Aspera on Cloud user.

A valid request for access token must:

  • Contain the user ID of any Aspera on Cloud user.
  • Be signed by that user's private key.

API client can request access as any Aspera on Cloud user.

A valid request for access token must:
  • Contain the user ID of any Aspera on Cloud user.
  • Be signed by that user's private key or by the global private key.
Only Listed Users

API client can request access as any eligible (listed) Aspera on Cloud user.

A valid request for access token must:
  • Contain the user ID of a listed Aspera on Cloud user.
  • Be signed by that listed user's private key.

API client can request access as any eligible (listed) Aspera on Cloud user.

A valid request for access token must:
  • Contain the user ID of a listed Aspera on Cloud user.
  • Be signed by that listed user's private key or the global private key.

Procedure

Edit online

To configure JWT authentication for your registered client application, do the following:

Note: This procedure assumes that you have already entered the public keys required in the appropriate user record. To add a key to your own user record, see Add your public key. If you are an admin, see Create and manage users to update your record or another user's record with a public key.
  1. When viewing your integration, click JSON Web Token Auth.
  2. Select Enable JWT grant type.
  3. To enable administrative users of this client to retrieve an administrator-scoped client, select the check box labeled Enable AoC administrators to retrieve a transfer node token that grants node administrator permissions.
  4. Select which keys your API client can use to retrieve tokens for the users you specify in the next step:
    1. To allow your API client to use only the user-specific keys for the users listed below, select User-specific keys.
    2. To allow your API client to use either user-specific keys or a global key to retrieve access tokens, select User-specific keys and global key. In the text box that appears, enter the global public key.
  5. Select the users for which your API client can retrieve access tokens:
    1. To allow your API client to retrieve tokens for all users in the Aspera on Cloud organization, select All users.
    2. To restrict your API client to retrieving tokens for a specific list of users or groups, select Only selected users and enter the user names or group names in the text box.
  6. Click Save.

Managing registered clients

Edit online

You can retrieve your client ID and secret, display and update details for any registered client, and delete a client.

  1. In the Admin application, select Integrations > API clients.
  2. To delete a client, right-click the row and select Delete; then confirm deletion.
  3. To open any client record and display the client ID and secret, click the row.
  4. Edit other fields as required, then click Save.
  5. To delete this client, click Delete, then confirm deletion.