Skip to content

Cloud Connect

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 will be transferred automatically to each external cloud storage account.

Create Cloud Connection

Authorized users can create cloud connections under any team they belong to (subject to access policy).

POST /teams/{{team_id}}/cloud_connections

HEADERS
Name Type Required Description
X-User-Token String Yes User JSON Web Token
Content-Type String Yes Must be application/json
BODY
Name Type Required Description
name String No Name of the connection to create
provider String Yes Cloud storage provider to connect
authorization Object Yes Authorization credentials - specific each provider, examples below
REQUEST
curl -H "X-User-Token: $USER_TOKEN" -H "Content-Type: application/json" -X POST https://api.massive.app/v1/teams/$TEAM_ID/cloud_connections -d '{"name": "$NAME", "provider": "$PROVIDER", "authorization": "$", "authorization": {"$KEY1":"$VALUE1", "$KEY2":"$VALUE2"}}'

Where:

  • $USER_TOKEN is the auth token returned during auth request (refer to Authorization: Login section of this document)
  • $TEAM_ID is the team ID returned during auth request (refer to Authorization: Login section of this document)

The credentials will be validated to ensure proper access to the storage provider account. After a successful request where a cloud connection has been created, this endpoint will return an HTTP response with a status code of 201 Created and a body similar to the one below.

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

Where:

  • id is the created connection ID.

Provider Examples

MASV currently integrates with a plethora of cloud storage providers. The following examples show the provider value and authorization object that is specific to each of them.

Attention

All provider authorization fields are required, unless noted otherwise

Amazon S3

MASV supports uploading to an Amazon S3 bucket in any region. The key must be scoped with s3:PutObject, s3:AbortMultipartUpload, s3:ListBucket, s3:DeleteObject, and s3:GetBucketLocation permissions on the bucket.

The provider value is amazon_s3

Sample Authorization
Name Type Description
client_id String Access key ID generated in AWS with access to this bucket
client_secret String Access key secret provided by AWS for the key ID above
destination String Name of the bucket that files will be transferred to
region String AWS region that the bucket is located in (ie. us-east-1, etc.). This must match one of the region codes listed here
References

Backblaze B2

MASV supports uploading to a Backblaze B2 bucket using an Application Key with Read and Write access on the target bucket.

The provider value is backblazeb2

Sample Authorization
Name Type Description
client_id String Key ID generated in Backblaze with access to this bucket
client_secret String Application key provided by Backblaze for the key ID above
destination String Name of the bucket that files will be transferred to
References

Box

MASV supports uploading to Box using a Custom Box Application that must be created first and then the contents of the configuration file must be provided as described below.

The provider value is box

Sample Authorization
Name Type Description
client_id String Client ID value in the Public/Private keypair json file generated for the Box application
client_secret String Client secret value in the Public/Private keypair json file generated for the Box application
public_key_id String Public key id value in the Public/Private keypair json file generated for the Box application
private_key String Private key value in the Public/Private keypair json file generated for the Box application. The entire key including "-----BEGIN ENCRYPTED PRIVATE KEY..." to "...END ENCRYPTED PRIVATE KEY-----" must be provided unaltered.
passphrase String Passphrase value in the Public/Private keypair json file generated for the Box application
enterprise_id String Enterprise ID value in the Public/Private keypair json file generated for the Box application
References

DigitalOcean

MASV supports uploading to a DigitalOcean Space in any region. The key must be scoped with access to read and write objects on the specified bucket.

The provider value is digital_ocean_s3

Sample Authorization
Name Type Description
client_id String Access key ID generated in DigitalOcean with access to this bucket
client_secret String Access key secret provided by DigitalOcean for the key ID above
destination String Name of the bucket that files will be transferred to
endpoint String Region URL that the bucket is stored in (ie. sfo2.digitaloceanspaces.com, nyc3.digitaloceanspaces.com, ams3.digitaloceanspaces.com)
region String DigitalOcean region that the bucket is located in (ie. sfo2, nyc3, ams3, etc.)
References

Frame.io

MASV supports uploading to a specific Frame.io project using a custom Developer Token that has the following scopes:

  • Teams: read
  • Assets: delete, create, update, read
  • Account: read
  • Project: read

The provider value is frameio

Sample Authorization
Name Type Description
developer_token String Frame.io developer token
account_id String Frame.io account that the team and project belong to
team_id String Frame.io team id that the project belongs to
project_id String Frame.io project that the files will be uploaded to
References

Google Cloud Storage

MASV supports uploading to Google Cloud Storage using a Service Account that must be created first and then the contents of the configuration file must be provided as described below. The Service Account must have the 'Storage Object Admin' role on your bucket.

The provider value is google_cloud_storage

Sample Authorization
Name Type Description
client_email String Client Email of the GCS Service Account
private_key String Private Key from the GCS Service Account. The entire key including "-----BEGIN PRIVATE KEY..." to "...END PRIVATE KEY-----" must be provided unaltered.
destination String Name of the bucket that files will be transferred to
References

Minio

MASV supports uploading to a Minio bucket using an access key. The key must be scoped with access to read and write objects on the specified bucket.

The provider value is minio_s3

Sample Authorization
Name Type Description
client_id String Access key ID generated in Minio with access to this bucket
client_secret String Access key secret provided by Minio for the key ID above
destination String Name of the bucket that files will be transferred to
endpoint String URL for the bucket
region String Region URL that the bucket is stored, typically "default" unless you have configured special regions or subdomains for the minio bucket
force_s3_path_style String Boolean indicates whether the bucket name should be placed as a subdomain or as part of the path (ie. https://bucketname.endpoint/ vs https://endpoint/bucketname)
References

Postlab

MASV supports uploading to a specific Postlab team using a team key.

The provider value is postlab

Sample Authorization
Name Type Description
team_id String Postlab team key - You can obtain the team key by opening Postlab app Preferences, then going to Integrations > MASV.

Wasabi

MASV supports uploading to a Wasabi Cloud Storage in any region using an access key. The key must be scoped with access to read and write objects on the specified bucket.

The provider value is wasabi_s3

Sample Authorization
Name Type Description
client_id String Access key ID generated in Wasabi with access to this bucket
client_secret String Access key secret provided by Wasabi for the key ID above
destination String Name of the bucket that files will be transferred to
endpoint String Region URL that the bucket is stored in (ie. s3.us-east-1.wasabisys.com)
region String DigitalOcean region that the bucket is located in (ie. us-east-1, us-east-2, us-west-1, etc.)
References

Other S3 Compatible Storage

MASV supports uploading to any S3 Compatible cloud storage provider. The access key must be scoped so that it can read and write objects on the specified bucket.

The provider value is generic_s3

Sample Authorization
Name Type Description
client_id String Access key ID generated in provider with access to this bucket
client_secret String Access key secret provided by provider for the key ID above
destination String Name of the bucket that files will be transferred to
endpoint String URL for the bucket
region String Region URL that the bucket is stored - if there isn't one you may pass "default"
force_s3_path_style String Boolean indicates whether the bucket name should be placed as a subdomain or as part of the path (ie. https://bucketname.endpoint/ vs https://endpoint/bucketname)

List Cloud Connections

Authorized users can list all cloud connections under any team they belong to (subject to access policy).

GET /teams/{team_id}/cloud_connections

HEADERS
Name Type Required Description
X-User-Token String Yes User JSON Web Token
REQUEST
curl -H `X-User-Token: $USER_TOKEN` -X GET https://api.massive.app/v1/teams/$TEAM_ID/cloud_connections

Where:

  • $USER_TOKEN is the auth token returned during auth request (refer to Authorization: Login section of this document)
  • $TEAM_ID is the team ID returned during auth request (refer to Authorization: Login section of this document)

After a successful request, this endpoint will return an HTTP response with a status code of 200 OK and a body similar to the one below.

[
     {
        "connections": 1,
        "created_at": "2020-08-18T13:29:06.698Z",
        "id": "01EG0W4MWA5CA1DXXZRFBRC4VM",
        "name": "Backblaze Bucket",
        "provider": "backblazeb2",
        "state": "ok",
        "updated_at": "2020-08-18T09:29:06.701Z"
    },
    {
        "created_at": "2020-08-28T14:03:05.623Z",
        "id": "01EGTP220QMPHMMF9JDN1KJQTE",
        "name": "Postlab Account",
        "provider": "postlab",
        "state": "ok",
        "updated_at": "2020-08-28T10:04:31.337Z"
    },
    ...
]

Update Cloud Connection

Authorized users can update cloud connections under any team they belong to (subject to access policy).

PUT /cloud_connections/{connection_id}

HEADERS
Name Type Required Description
X-User-Token String Yes User JSON Web Token
Content-Type String Yes Must be application/json
BODY
Name Type Required Description
name String No Name of the connection
authorization Object No Authorization credentials - specific each provider
REQUEST
curl -H "X-User-Token: $USER_TOKEN" -H "Content-Type: application/json" -X PUT https://api.massive.app/v1/cloud_connections/$CONNECTION_ID -d '{"name": "$NAME", "authorization": "$", "authorization": {"$KEY1":"$VALUE1", "$KEY2":"$VALUE2"}}'

Where:

  • $USER_TOKEN is the auth token returned during auth request (refer to Authorization: Login section of this document)
  • $CONNECTION_ID is the connection ID returned during creation

Any authorization properties that are not provided will be assumed to be unchanged. The credentials will be validated to ensure proper access to the storage provider account.

After a successful request where a cloud connection has been updated, this endpoint will return an HTTP response with a status code of 200 OK and a body similar to the one below.

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

Delete Cloud Connection

Authorized users can delete cloud connections under any team they belong to (subject to access policy).

DELETE /cloud_connections/{connection_id}

HEADERS
Name Type Required Description
X-User-Token String Yes User JSON Web Token
Content-Type String Yes Must be application/json
REQUEST
curl -H "X-User-Token: $USER_TOKEN" -H "Content-Type: application/json" -X PUT https://api.massive.app/v1/cloud_connections/$CONNECTION_ID -d '{"name": "$NAME", "authorization": "$", "authorization": {"$KEY1":"$VALUE1", "$KEY2":"$VALUE2"}}'

Where:

  • $USER_TOKEN is the auth token returned during auth request (refer to Authorization: Login section of this document)
  • $CONNECTION_ID is the connection ID returned during creation

After a successful deletion request, this endpoint will return an HTTP response with a status code of 204 No Content and an empty body. Any transfers that are in progress at the time of deletion will complete normally, however the associated portal recipients may not be notified. Any failed transfers will not be retriable once the connection has been deleted.

Using Cloud Connections

Once cloud connections are created, they have to be connected to any number of portals in order to enable automated delivery of packages uploaded to these portals into the specified connection. This section demonstrates how this can be achieved and show you how you can monitor the state of package deliveries.

Note

This section is focused on managing cloud connections only, for more details on managing Portals and a description of each property please refer to the Portals section of the API documentation

Attach Cloud Connection to Portal

Authorized users can attach cloud connections to a portal under any team they belong to (subject to access policy). This is managed by updating the Portal to specify the cloud connection(s) that should be attached to it - to remove a connection simply update without including it in the list of connections.

PUT /portals/{portal_id}

HEADERS
Name Type Required Description
X-User-Token String Yes User JSON Web Token
Content-Type String Yes Must be application/json
BODY
Name Type Required Description
cloud_connections Array of connections No List of associated connections
# CLOUD CONNECTION
Name Type Required Description
id String Yes ID of cloud connection
target_action String Yes Action to be taken with cloud connection
REQUEST
curl -H "X-User-Token: $USER_TOKEN" -H "Content-Type: application/json" -X PUT https://api.massive.app/v1/portals/$PORTAL_ID -d '{"name": "$NAME", "subdomain": "$PORTAL_SUBDOMAIN", "cloud_connections": [{"id":"$ID1", "target_action":"transfer"}, {"id":"$ID2", "target_action":"transfer"}]}'

Where:

  • $USER_TOKEN is the auth token returned during auth request (refer to Authorization: Login section of this document)
  • $PORTAL_ID is the portal ID to update
  • $NAME is the portal name (all portal properties are required on update)
  • $ID1 the first cloud connection, $ID2 the second cloud connection, etc.

Attention

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

After a successful request where a portal has been updated, this endpoint will return an HTTP response with a status code of 200 OK and a body similar to the one below.

{
        "active": true,
        "cloud_connections": [
            {
                "connections": 1,
                "created_at": "2020-09-15T13:32:27.906Z",
                "id": "01EJ8ZEXC2T8D1Y3ZAR3E6GGFB",
                "name": "Frame.io",
                "provider": "frameio",
                "state": "ok",
                "target_action": "transfer",
                "updated_at": "2020-09-15T10:34:39.442Z"
            },
            {
                "connections": 1,
                "created_at": "2020-09-15T13:46:37.854Z",
                "id": "01EJ908VCYMECVH5SPAV9YN92B",
                "name": "BackBlaze",
                "provider": "backblazeb2",
                "state": "ok",
                "target_action": "transfer",
                "updated_at": "2020-09-15T10:33:31.962Z"
            }
        ],
        "created_at": "2020-01-09T10:45:01.437Z",
        "id": "01DY5FNYFXQDZ5NBX482ZAMRG8",
        "name": "My Portal",
        "recipients": [],
        "subdomain": "myportal",
        "updated_at": "2020-10-06T16:18:28.034Z"
    }

List Portal Cloud Connections

Authorized users can list the cloud connections on a portal under any team they belong to (subject to access policy). This is visible by retrieving the list of Portals.

GET /teams/{team_id}/portals

HEADERS
Name Type Required Description
X-User-Token String Yes User JSON Web Token
REQUEST
curl -H `X-User-Token: $USER_TOKEN` -X GET https://api.massive.app/v1/teams/$TEAM_ID/portals

Where:

  • $USER_TOKEN is the auth token returned during auth request (refer to Authorization: Login section of this document)
  • $TEAM_ID is the team ID returned during auth request (refer to Authorization: Login section of this document)

After a successful request, this endpoint will return an HTTP response with a status code of 200 OK and a body similar to the one below.

[
    {
        "id": "01CNH24NGPTJTMXWWM2J8E2V8V",
        "message": "Hello world!",
        "name": "My portal",
        "subdomain": "myportal",
        "has_access_code": false,
        "recipients": [
            "[email protected]",
            "[email protected]"
        ],
        "cloud_connections": [
            {
                "connections": 1,
                "created_at": "2020-09-15T13:32:27.906Z",
                "id": "01EJ8ZEXC2T8D1Y3ZAR3E6GGFB",
                "name": "Frame.io",
                "provider": "frameio",
                "state": "ok",
                "target_action": "transfer",
                "updated_at": "2020-09-15T10:34:39.442Z"
            },
            {
                "connections": 2,
                "created_at": "2020-09-15T13:46:37.854Z",
                "id": "01EJ908VCYMECVH5SPAV9YN92B",
                "name": "BackBlaze",
                "provider": "backblazeb2",
                "state": "ok",
                "target_action": "transfer",
                "updated_at": "2020-09-15T10:33:31.962Z"
            }
        ],

    },
    {
        "id": "01CNEM9H2AG0MVH33X0EVDY8AQ",
        "message": "Hello world, again!",
        "name": "My other portal",
        "subdomain": "myotherportal",
        "has_access_code": false,
        "recipients": [
            "[email protected]"
        ],
        "cloud_connections": [
            {
                "connections": 5,
                "created_at": "2020-09-15T13:32:27.906Z",
                "id": "01EJ8ZEXC2T8D1Y3ZAR3E6GGFB",
                "name": "Amazon S3",
                "provider": "amazon_s3",
                "state": "ok",
                "target_action": "transfer",
                "updated_at": "2020-09-15T10:34:39.442Z"
            },
            {
                "connections": 2,
                "created_at": "2020-09-15T13:46:37.854Z",
                "id": "01EJ908VCYMECVH5SPAV9YN92B",
                "name": "BackBlaze",
                "provider": "backblazeb2",
                "state": "ok",
                "target_action": "transfer",
                "updated_at": "2020-09-15T10:33:31.962Z"
            }
        ],
    },
    ...
]

View Package Cloud Delivery Status

Authorized users can list package cloud deliveries for any package under their team(s) subject to access policy). The listing will include all transfers that are a associated to the uploaded package.

GET /packages/{package_id}/transfers

HEADERS
Name Type Required Description
X-Package-Token String Yes Package JSON Web Token
REQUEST
curl -H "X-Package-Token: $PACKAGE_TOKEN" -X GET https://api.massive.app/v1/packages/$PACKAGE_ID/transfers

Where:

  • $PACKAGE_ID is the ID of the package
  • $PACKAGE_TOKEN is the package access token

After a successful request, this endpoint will return an HTTP response with a status code of 200 OK and a body similar to the one below.

[
    {
        "created_at": "2020-10-06T19:25:54.206Z",
        "id": "01EKZP15MYQGJKW90N60AJHC9N",
        "provider": "google_cloud_storage",
        "retriable": false,
        "state": "completed",
        "updated_at": "2020-10-06T19:28:50.003Z"
    },
    {
        "created_at": "2020-10-06T19:23:42.521Z",
        "error_message": "insufficient_space",
        "id": "01EKZNX51ST2ZH1Z1AN2BBJ5WM",
        "provider": "frameio",
        "retriable": true,
        "state": "error",
        "updated_at": "2020-10-06T19:23:42.522Z"
    },
    ...
]

Where:

  • id is the transfer ID
  • state is the state of transfer, can be one of:
    • pending: the transfer has been queued and/or is in progress
    • completed: the transfer has finished successfully
    • cancelled: the transfer was aborted
    • error: the transfer failed, look at the error_message for a reason
  • error_message is an error key indicating why the transfer failed (if state is error), can be one of:
    • authentication_failed: the credentials supplied in the cloud connection were rejected by the cloud storage provider, either because they are invalid or have insufficient permissions
    • provider_unavailable: the cloud storage provider was unavailable and all automatic retry attempts were unsuccessful, possibly due to an outage or incorrect configuration
    • insufficient_space: the cloud storage provider indicated that there is not enough space for the package or that usage limits have been exceeded
    • directory_not_found: the target directory to place the package in does not exist or could not be created
  • provider is the cloud storage provider
  • retriable indicates if this transfer can be retried (refer to Cloud Connect: Retry a Failed Transfer of this document)

Retry a Failed Transfer

Authorized users can retry a failed package cloud delivery for any package under their team(s) subject to access policy). If the transfer has already been retried or the cloud connection is unavailable or the package has expired or it didn't fail then it cannot be retried.

POST /packages/{package_id}/transfer/{transfer_id}/retry

HEADERS
Name Type Required Description
X-Package-Token String Yes Package JSON Web Token
REQUEST
curl -H "X-Package-Token: $PACKAGE_TOKEN" -X POST https://api.massive.app/v1/packages/$PACKAGE_ID/transfers/$TRANSFER_ID/retry

Where:

  • $PACKAGE_ID is the ID of the package
  • $PACKAGE_TOKEN is the package access token
  • $TRANSFER_ID is the transfer to be retried

After a successful request, this endpoint will return an HTTP response with a status code of 201 Created and a body similar to the one below.

    {
        "created_at": "2020-10-06T19:25:54.206Z",
        "id": "01EKZP15MYQGJKW90N60AJHC9N",
        "provider": "google_cloud_storage",
        "retriable": false,
        "state": "pending",
        "updated_at": "2020-10-06T19:28:50.003Z"
    }