JSON 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.

Details about generating and using tokens for packages and transfers are covered in the other topics for the MASV API.

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