Media Shuttle Management API Integration Guide

The Media Shuttle Management API automates tasks performed using the IT Administration or Operations Administration Console, including portal and user account management, and can provide information about a portal's active transfers.

Account and Portal Requirements

Management automation requires the following:

• Access to the IT Administration Console and the Operations Administration Console.

• An API key.

Creating Portals

The /portals endpoint allows you to create a new Send, Share, or Submit portal via the Management API.

To create a new portal:

1. Create a new JSON file specifying the new portal details, including the relevant configuration options for the portal type:

{
   "name": "New Share Portal",
   "url": "example.mediashuttle.com",
   "type": "share",
   "authentication":{
      "mediaShuttle": true
   },
   "linkAuthentication":{
      "allowUnauthenticatedUploads": false,
      "allowUnauthenticatedDownloads": false
   },
   "notifyMembers": true
}

2. Save the file as newPortal.json.

3. In your terminal or command prompt, navigate to the directory where newPortal.json is stored.

4. Use the curl utility to POST to the /portals endpoint, including the API token in the header and newPortal.json as the request body:

curl -X POST "https://api.mediashuttle.com/v1/portals" \
 -H "Accept: application/json" \
 -H "Authorization: 12345678-1234-45f7-b9fc-6175f06cebed" \
 -H "Content-Type: application/json" \
 --data @newPortal.json

The response body contains the portal details, including the id which is used as the portalId when assigning storage to the portal. This can be done using the /portals/{portalId}/storage/{storageId} endpoint. For more information about assigning storage to a portal using the API, see the Media Shuttle API Documentation.

Note: Storage must be deployed using the IT Administration Console. For more information, see the Signiant Help Center.

The following image outlines the general workflow for creating a new portal using the Media Shuttle Management API.

Updating Portal Configuration

The /portals/{portalId} endpoint allows you to modify an existing portal's properties, including its name and security configuration.

1. Create a new JSON file specifying the new portal details, including the relevant configuration changes:

   Copy

   {
      "authentication": {
         "mediaShuttle": true,
         "saml": true
      },
      "linkAuthentication": {
         "allowUnauthenticatedUploads": true,
         "allowUnauthenticatedDownloads": true
      }
   }

2. Save the file as portalChanges.json.

3. In your terminal or command prompt, navigate to the directory where portalChanges.json is stored.

4. Use the curl utility to PATCH the /portals/{portalId} endpoint, including the API token in the header and portalChanges.json as the request body:

curl -X PATCH "https://api.mediashuttle.com/v1/portals/abcdefab-abcd-1234-abcd-6175f06cebed" \
 -H "accept: application/json" \
 -H "Authorization: 12345678-1234-45f7-b9fc-6175f06cebed" \
 -H "Content-Type: application/json" \
 --data @portalChanges.json

Viewing Active Transfers

The /transfers endpoint allows you to view transfer activity across all portals, including details about the transfer state and protocol, as well as the transfer rate, current file, and more.

Once a transfer begins, the /transfers endpoint provides the progress, transfer direction, time remaining, and other details for all portals associated with your account. Once a transfer completes, its details are no longer available through the /transfers endpoint.

To view all active transfers, send a GET request to the /transfers endpoint, including the API token in the header:

curl -X GET "https://api.mediashuttle.com/v1/transfers?state=active" \
 -H "Authorization: 12345678-1234-45f7-b9fc-6175f06cebed"

Note: All requests to the transfers endpoint must include the ?state=active query parameter. Completed, failed, and cancelled transfers cannot be viewed using the /transfers endpoint.

To view active transfers for a specific portal, include the portalId as a query parameter:

curl -X GET "https://api.mediashuttle.com/v1/transfers?state=active&portalId=abcdefab-abcd-1234-abcd-6175f06cebed" \
 -H "Authorization: 12345678-1234-45f7-b9fc-6175f06cebed"

Portal Authentication Methods

Creating or modifying a Media Shuttle portal using the API allows you to set the portal authentication method, which can be a user name and password combination, or SAML single sign-on, allowing a third party identity provider to manage portal access.

To configure a SAML identity provider and required parameters, you must have access to the IT Administration Console and configure an Account Level identity provider via the Security page. For more information about configuring SAML for Media Shuttle, see the Signiant Help Center.

Once an identity provider is configured, any portal created via the API must use an account level identity provider. Setting a portal level identity provider must be done via the IT Administration Console.

Note: Signiant Platform SAML cannot be used in combination with Media Shuttle SAML, and cannot be enabled or modified via the API. For more information, see the Signiant Help Center or contact Signiant Customer Care.

Authentication Examples

Using GET to view a portal's configuration provides the authentication details within the response body. The following examples describe common authentication methods.

Media Shuttle user name and password only authentication

{
   "authentication": {
      "mediashuttle": true,
      "saml": false

   }
}

Media Shuttle SAML only authentication

{
   "authentication": {
      "mediashuttle": false,
      "saml": true

   }
}

Signiant Platform SAML only authentication

The saml parameter refers to Media Shuttle SAML, and will return false if Platform SAML is enabled. Platform SAML cannot be enabled or modified via the API.

{
   "authentication": {
      "mediashuttle": false,
      "saml": false

   }
}