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 -d '{"email": "$EMAIL_ADDRESS", "password": "$PASSWORD"}' \
  -H "Content-Type: application/json" \
  -X POST https://api.massive.app/v1/auth

Response

After successful authentication, this endpoint returns 200 OK:

{
  "teams": [
    {
      "id": "01D377KWTJDPC8JQC6XVGPMHDW",
      "name": "Default Team",
      "subdomain": "a8fc91fa"
    }
  ],
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "email": "api@masv.io",
    "id": "01D398ZWSXWS8YBZKXCW56BF4H",
    "level": "basic",
    "name": "MASV API",
    "preferred_team_id": "01FB4S68W7RAW4M89801H1C4CR",
    "primary_team_id": "01FB4S68W7RAW4M89801H1C4CR",
    "time_zone": "EST"
  }
}

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 JWTs 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 used to request them:

• Write access (limited): Granted by the initial create Portal package request. Restricted to actions needed to complete the upload — 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 authenticating with link credentials. Used primarily for downloading package files. Limited to reading package details, 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 managing packages owned by the account. Returned when fetching the list of packages or when sending a package. Permits editing package details (name, expiry), creating additional links, deleting the package, and viewing or initiating transfers to connected storage integrations. Does not directly permit downloads — 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 JWTs to interact with transfers to connected storage. These tokens are authorized to interact with an individual transfer and are limited to reading the transfer status, 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