Web tokens

The MASV API uses JSON Web Token (JWT) to authorize some requests. These requests must have the appropriate header field:

• X-Package-Token: For accessing a package. Examples: uploads and downloads.
• X-Transfer-Token: For accessing a transfer to and from a cloud connection.
• X-User-Token: For user requests.

User tokens

The recommended way to authorize user requests is with an API key. However, the MASV API also accepts a JWT instead. The primary use of Web Tokens in user requests is to manage user accounts and API keys.

For endpoints that require it, your request must have the X-User-Token header set:

Name	Type	Required	Description
X-User-Token	String	Yes	token from an auth response

Generate a user token

To generate a user token requires a MASV user's email and password.

Note

The JSON Web Token that you receive carries the same privileges as your logged-in user. Keep this safe and secure!

Note

If your account requires MFA, you will need to turn off MFA in the MASV Web App before generating a JWT.

Method	Route
POST	/auth

HEADERS

Name	Type	Required	Description
Content-Type	String	Yes	Must be application/json

BODY

Name	Type	Required	Description
email	String	Yes	Email address associated with MASV Account
password	String	Yes	Login password associated with MASV Account

REQUEST

curl

curl -d '{"email": "$EMAIL_ADDRESS", "password": "$PASSWORD"}' \
 -H 'Content-Type: application/json' \
 -s -X POST https://api.massive.app/v1/auth

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

Example JSON Response

{
  "teams ": [
    {
      "id ": "01D377KWTJDPC8JQC6XVGPMHDW",
      "name ": "Default Team",
      "subdomain ": "a8fc91fa"
    }
  ],
  "token ": "eyJhbGciOiJIUcI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1NTQ0MDUzNjQsImV4dCI6e30sImltcCI6ZmFsc2UsInN1YiI6IjAxRDM5OEtXTjlBWEI3NkgyRUZONFcwOVFIIn0.DlqkZSTg68wQ9bjkZlcYigvb41owmPlRK2KJloiGUUw ",
  "user ": {
    "email ": "[email protected]",
    "id ": "01D398ZWSXWS8YBZKXCW56BF4H",
    "level ": "basic",
    "name ": "MASV API",
    "preferred_team_id":"01FB4S68W7RAW4M89801H1C4CR",
    "primary_team_id":"01FB4S68W7RAW4M89801H1C4CR",
    "time_zone ": "EST",
  }
}

Response Properties:

Property	Description
teams	An array of all teams the user belongs to
token	The JWT, ready for user-related API calls
user	User information for the logged in user

Package tokens

The MASV API requires special JWT to interact with packages. These tokens are authorized to interact with a single package, rather than all packages.

Package tokens come in one of three variants, depending on the authentication mechanism that was used to request them:

• Write access (limited): Granted by the initial create portal package request where the client is restricted to actions needed to complete the upload. This token is limited to creating files and finalizing the package, without the ability to create links, edit the package expiry or initiate transfers to connected storage.
• Read access (limited): Granted by the authenticating with link credentials request and used primarily for downloading package files. This token is limited to reading details about the package, though it does allow clients to initiate transfers to cloud storage when providing single-use credentials.
• Management access: Granted when authenticating with user credentials (user token or API key) for the purpose of managing packages owned by the account. This token is returned when fetching the list of packages or when sending a package. It is permitted to edit the package details (ie. name, expiry), create additional links, delete the package, and to view or initiate transfers to connected storage integrations. This token access does not directly permit downloads of the package files; instead, a link must be created and authenticated to get a read access token.

For endpoints that require it, your request must have the X-Package-Token header set:

Name	Type	Required	Description
X-Package-Token	String	Yes	access_token from a package response

Transfer tokens

The MASV API requires special JWT to interact with transfers to connected storage. These tokens are authorized to interact with an individual transfer and are limited to reading the status of the transfer, retrying it, or cancelling it. Transfer tokens are returned when initiating a new transfer or when fetching the list of transfers for a specific package.

For endpoints that require it, your request must have the X-Transfer-Token header set:

Name	Type	Required	Description
X-Transfer-Token	String	Yes	access_token from a transfer response