Cloud Connections

The MASV API allows authorized users to connect their Portals to an external cloud storage provider by way of Cloud Connect. The connection details are entered once and can be reused across multiple Portals. Each Portal can have one or more connections attached, and as new uploads are received they are transferred automatically to each external cloud storage account.

You can create cloud connections for storage device integrations by installing the MASV Agent on the device and configuring a storage gateway. See Provider examples for information about specific storage devices.

Create cloud connection

Method	Route
POST	/teams/{team_id}/cloud_connections

Headers

Name	Type	Required	Description
X-API-KEY	String	Yes	API key
Content-Type	String	Yes	Must be application/json

Body

Name	Type	Required	Description
name	String	No	Name of the connection
provider	String	Yes	Cloud storage provider
direction	String	No	masv_to_cloud or cloud_to_masv. Default: masv_to_cloud
authorization	Object	Yes	Authorization credentials, specific to each provider
target_directory_id	String	No	Custom directory path for package files (masv_to_cloud only)
source_directory_ids	String[]	No	Source directories for filepicker (cloud_to_masv only)
upload_transfer_manifest	Boolean	No	Generate a JSON manifest file for transfers (S3 and S3-compatible only)

Request (MASV to cloud)

curl -d '{"name": "$NAME", "provider": "$PROVIDER", "direction": "masv_to_cloud", "authorization": {"$KEY1":"$VALUE1"}, "target_directory_id":"$TARGET_DIR"}' \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -X POST https://api.massive.app/v1/teams/$TEAM_ID/cloud_connections

Request (Cloud to MASV)

For the cloud_to_masv direction, your application can send from the amazon_s3 and wasabi_s3 providers.

curl -d '{"name": "$NAME", "provider": "$PROVIDER", "direction": "cloud_to_masv", "authorization": {"$KEY1":"$VALUE1"}, "source_directory_ids":["$SOURCE_DIR"]}' \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -X POST https://api.massive.app/v1/teams/$TEAM_ID/cloud_connections

Response

Returns 201 Created:

{
  "created_at": "2020-10-06T12:44:19.369Z",
  "direction": "masv_to_cloud",
  "id": "01EKYZ1VH9GTS9GYMCMSR4NR9G",
  "name": "Sample Connection",
  "provider": "amazon_s3",
  "state": "ok",
  "updated_at": "2020-10-06T12:44:19.369Z"
}

Provider examples

MASV integrates with a growing list of cloud storage providers. All provider authorization fields are required unless noted otherwise.

Amazon S3

Provider value: amazon_s3

MASV supports transfers to or from an Amazon S3 bucket in any region. You must create an IAM policy with the required permissions.

masv_to_cloud permissions: s3:PutObject, s3:AbortMultipartUpload, s3:ListBucket, s3:DeleteObject, s3:GetBucketLocation

cloud_to_masv permissions: s3:GetObject, s3:ListBucket

Key-based access

Attach the IAM policy to an IAM user and create an access key.

Role-based access

Attach the IAM policy to an IAM role with a trust policy allowing MASV to assume the role. This model does not require routine key rotation.

Authorization

Name	Type	Description
client_id	String	Access key ID (key-based access only)
client_secret	String	Access key secret (key-based access only)
role_arn	String	ARN of the IAM role (role-based access only)
external_id	String	External ID in trust policy (role-based access only)
destination	String	Bucket name
region	String	AWS region (e.g., us-east-1)
storage_class	String	S3 storage class: STANDARD, INTELLIGENT_TIERING, STANDARD_IA, ONEZONE_IA, GLACIER_IR, GLACIER, or DEEP_ARCHIVE. Default: STANDARD

Amazon EBS/EFS

Provider value: amazon_efs_sg

Create a cloud connection with Amazon EBS or EFS storage that has the MASV Agent installed via a storage gateway.

Note

Storage gateway connections do not pass authorization. The MASV API generates the credentials for the MASV Agent.

Azure Storage

Provider value: azure

MASV supports uploading to an Azure storage container using a Shared Access Signature (SAS) URI with Blob service access on Object and Container resource types.

Name	Type	Description
blob_service_sas_url	String	A Blob service SAS URL
destination	String	Name of the container

Backblaze B2

Provider value: backblazeb2

Name	Type	Description
client_id	String	Key ID with access to the bucket
client_secret	String	Application key
destination	String	Bucket name

Box

Provider value: box

Name	Type	Description
client_id	String	Client ID from Box keypair JSON
client_secret	String	Client secret from Box keypair JSON
public_key_id	String	Public key ID
private_key	String	Private key (full PEM format)
passphrase	String	Passphrase
enterprise_id	String	Enterprise ID

Desktop Mounted Storage

Provider value: desktop_sg

Connect via MASV Desktop App with a storage gateway.

DigitalOcean

Provider value: digital_ocean_s3

Name	Type	Description
client_id	String	Access key ID
client_secret	String	Access key secret
destination	String	Bucket name
endpoint	String	Region URL (e.g., sfo2.digitaloceanspaces.com)
region	String	Region (e.g., sfo2)

Frame.io

Provider value: frameio_v4

Name	Type	Description
auth_strategy	String	Must be server
client_id	String	Adobe S2S project client ID
client_secret	String	Adobe S2S project client secret
account_id	String	Frame.io account ID
workspace_id	String	Frame.io workspace ID
project_id	String	Frame.io project ID

Frame.io (Legacy)

Provider value: frameio

Name	Type	Description
developer_token	String	Frame.io developer token
account_id	String	Frame.io account ID
team_id	String	Frame.io team ID
project_id	String	Frame.io project ID

Google Cloud Storage

Provider value: google_cloud_storage

Name	Type	Description
client_email	String	Client email of the GCS Service Account
private_key	String	Private key (full PEM format)
destination	String	Bucket name

IBM Cloud Object Storage

Provider value: ibm_cloud_s3

Name	Type	Description
client_id	String	Access key ID
client_secret	String	Access key secret
destination	String	Bucket name
endpoint	String	Region URL
region	String	Region (e.g., us-east)

Iconik

Provider value: iconik

Name	Type	Description
application_id	String	Iconik application ID
application_token	String	Iconik application token
storage_id	String	Iconik storage account ID

Jellyfish

Provider value: jellyfish_sg

Connect via MASV Agent with a storage gateway.

Minio

Provider value: minio_s3

Name	Type	Description
client_id	String	Access key ID
client_secret	String	Access key secret
destination	String	Bucket name
endpoint	String	URL for the bucket
region	String	Region (typically default)
force_s3_path_style	String	Whether to use path-style URLs

Object Matrix

Provider value: object_matrix_s3

Name	Type	Description
client_id	String	Access key ID
client_secret	String	Access key secret
destination	String	Bucket name
endpoint	String	URL (e.g., spacename.matrixstore.cloud:12323)
region	String	Must be eu

OpenDrives

Provider value: opendrives_sg

Connect via MASV Agent with a storage gateway.

PostLab

Provider value: postlab

Name	Type	Description
team_id	String	PostLab team key

QNAP

Provider value: qnap_sg

Connect via MASV Agent with a storage gateway.

Seagate Lyve Cloud

Provider value: lyve_cloud_s3

Name	Type	Description
client_id	String	Access key ID
client_secret	String	Access key secret
destination	String	Bucket name
endpoint	String	Region URL
region	String	Region

Storj

Provider value: storj_s3

Name	Type	Description
client_id	String	Access key ID
client_secret	String	Access key secret
destination	String	Bucket name
endpoint	String	URL (e.g., https://gateway.storjshare.io)
region	String	Should be default

Synology

Provider value: synology_sg

Connect via MASV Agent with a storage gateway.

Wasabi

Provider value: wasabi_s3

Name	Type	Description
client_id	String	Access key ID
client_secret	String	Access key secret
destination	String	Bucket name
endpoint	String	Region URL (e.g., s3.us-east-1.wasabisys.com)
region	String	Region

Other S3-compatible storage

Provider value: generic_s3

Name	Type	Description
client_id	String	Access key ID
client_secret	String	Access key secret
destination	String	Bucket name
endpoint	String	URL for the bucket
region	String	Region (use default if none)
force_s3_path_style	String	Whether to use path-style URLs

Other Storage Devices

Provider value: storage_gateway

Connect any NAS or SAN with the MASV Agent installed via a storage gateway.

List cloud connections

Method	Route
GET	/teams/{team_id}/cloud_connections

Request

curl -H "X-API-KEY: $API_KEY" \
  -X GET https://api.massive.app/v1/teams/$TEAM_ID/cloud_connections

Response

Returns 200 OK with an array of connection objects.

Update cloud connection

Method	Route
PUT	/cloud_connections/{connection_id}

Body

Name	Type	Required	Description
name	String	No	Name of the connection
authorization	Object	No	Authorization credentials

Any authorization properties not provided will be assumed unchanged.

Request

curl -d '{"name": "$NAME", "authorization": {"$KEY1":"$VALUE1"}}' \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -X PUT https://api.massive.app/v1/cloud_connections/$CONNECTION_ID

Response

Returns 200 OK with the updated connection object.

Delete cloud connection

Method	Route
DELETE	/cloud_connections/{connection_id}

Request

curl -H "X-API-KEY: $API_KEY" \
  -X DELETE https://api.massive.app/v1/cloud_connections/$CONNECTION_ID

Response

Returns 204 No Content. In-progress transfers will complete normally.

Attach cloud connections to Portals

Manage cloud connections by updating the Portal with a list of connections to enable.

Method	Route
PUT	/portals/{portal_id}

Body

Name	Type	Required	Description
cloud_connections	Object[]	No	List of connections with id, target_action, and optional filter_id
configure_cloud_connections	Boolean	Yes	Must be true to update connections

Request

curl -d '{"name": "$NAME", "subdomain": "$SUBDOMAIN", "configure_cloud_connections": true, "cloud_connections": [{"id":"$ID1", "target_action":"transfer"}], "active": true, "has_access_code": false}' \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -X PUT https://api.massive.app/v1/portals/$PORTAL_ID

Caution

All attached cloud connections must be provided in each update or else they will be removed.

Initiate a manual package transfer

Method	Route
POST	/packages/{package_id}/transfer

Headers

Name	Type	Required	Description
X-Package-Token	String	Yes	Package JSON Web Token

Body

Name	Type	Required	Description
cloud_connection_id	String	Yes	ID of the cloud connection
notify_email	String	No	Email to notify when transfer completes
files	Object[]	No	Files/directories to transfer (cloud_to_masv only)

Request (MASV to cloud)

curl -H "X-Package-Token: $PACKAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST https://api.massive.app/v1/packages/$PACKAGE_ID/transfer \
  -d '{"notify_email": "$EMAIL", "cloud_connection_id": "$CONNECTION_ID"}'