Skip to content

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.


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


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
Name Type Required Description
Content-Type String Yes Must be application/json
Name Type Required Description
email String Yes Email address associated with MASV Account
password String Yes Login password associated with MASV Account
curl -d '{"email": "$EMAIL_ADDRESS", "password": "$PASSWORD"}' \
 -H 'Content-Type: application/json' \
 -s -X POST

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.

  "teams ": [
      "id ": "01D377KWTJDPC8JQC6XVGPMHDW",
      "name ": "Default Team",
      "subdomain ": "a8fc91fa"
  "token ": "eyJhbGciOiJIUcI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1NTQ0MDUzNjQsImV4dCI6e30sImltcCI6ZmFsc2UsInN1YiI6IjAxRDM5OEtXTjlBWEI3NkgyRUZONFcwOVFIIn0.DlqkZSTg68wQ9bjkZlcYigvb41owmPlRK2KJloiGUUw ",
  "user ": {
    "email ": "[email protected]",
    "id ": "01D398ZWSXWS8YBZKXCW56BF4H",
    "level ": "basic",
    "name ": "MASV API",
    "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