Getting Started with Media Shuttle API

Signiant Media Shuttle APIs allow you to automate and integrate Media Shuttle with other applications or workflows. The Media Shuttle Management API controls portal management, storage, and active transfer status. The System-To-Person API allows end-users to upload or download files and integrate accelerated Media Shuttle transfers using Signiant Flight Deck, media asset managers, digital asset managers, or other applications.

Read the Media Shuttle API documentation

API Access

To use the Media Shuttle API, you must have an API key, which is found in the IT Administration Console.

  1. Log in to your IT Administration Console.
  2. Click your user name to open the menu.

  3. Click Developer to view your API key.

    Account menu developer

  4. Click Copy to Clipboard to copy your API key to the clipboard.

To revoke API access to your Media Shuttle account, click Regenerate API key.

Management API

Media Shuttle Management API automates tasks performed using the IT Administration or Operations Administration Console. The Management API allows automated portal management, user account management, authentication methods, and provides information about active transfers.

All Media Shuttle subscriptions include Media Shuttle Management API.

Modifying Portal Authentication Methods

The Media Shuttle management API allows you to configure the portal authentication type, allowing you to select Media Shuttle user name and password authentication and/or SAML Single Sign-On using a third-party identity provider such as Azure Active Directory or Okta.

Note: Signiant Platform SAML cannot be enabled or modified via the API.

Media Shuttle 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.

SAML single sign-on configuration cannot be set via the API. 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.

Signiant Platform Authentication Methods

In addition to configuring a user name and password or single sign-on via Media Shuttle, you can also select Platform SAML, which provides single sign-on authentication to Media Shuttle, Jet, and Flight Deck via the Signiant Console. Platform SAML must be enabled by Signiant Customer Care.

Note: Signiant Platform SAML cannot be used in combination with Media Shuttle SAML.

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,

   }
}

Workflow Example - Creating a New Portal

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,
   "contactForm":{
      "url":"https://example.com",
      "width":70,
      "height":65
   }
}

  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.

Media Shuttle Create a New Portal Workflow

Workflow Example - 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:

    {
   "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

Workflow Example - 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.

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

curl -X POST 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.

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

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

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

Media Shuttle View Active Transfers Workflow

System-to-Person Automation API

The System-to-Person API integrates Media Shuttle with other systems in your media technology workflow, including other Signiant applications.

Automated workflows driven by Signiant Flight Deck or Jet can deliver content from systems to individual users. Other systems such as a DAM or MAM can integrate Media Shuttle to your workflow for fast, easy, and secure content exchange.

Contact us today to learn more about the System-to-Person Automation API

Webhooks

Signiant’s System-to-Person API allows you to create webhooks that authorize your application to receive information about portal events.

Webhooks send subscription updates to a URL when a transfer finishes.

Learn more about System-to-Person webhooks

Workflow Example - Creating an Upload/Download Token

The following image outlines the general workflow for creating an upload or download token for a Share Portal using the Media Shuttle System-to-Person Automation API.

Media Shuttle Upload Download Token Workflow