Authentication

Some actions require a valid user session. For example, MASV Agent requires a valid user session when sending a Package to an email recipient or creating download automations. Other actions, like uploading to a Portal, do not require a user session.

When you try to perform an action without a valid session, the service responds with a 401 Unauthorized status code:

{
  "code": 262146,
  "message": "session is nil"
}

Authenticate with an API key

We recommend authenticating through an API key. Once you have generated your API key, pass it as a flag when you start the server:

masv server start --api-key='YOUR_KEY'

Authenticate with credentials

Use the following command to log in with your email and password.

CLI

masv user login --email {EMAIL} --password {PASSWORD}

REST API

curl -X POST -H "Content-Type: application/json" \
  http://localhost:8080/api/v1/login \
  -d '{"email":"EMAIL","password":"PASSWORD"}'

Check the current session

To see which user currently has a valid session with MASV Agent:

CLI

masv user status

REST API

curl -X GET http://localhost:8080/api/v1/login

The response includes the logged-in user and their Teams:

{
  "user": {
    "email": "me@domain.tld",
    "id": "01CWEEY5PT3535ETT4TH9NYZVP",
    "name": "Firstname Lastname"
  },
  "teams": [
    {
      "custom_expiry_default": 30,
      "custom_expiry_enabled": true,
      "download_limit_default": 12,
      "download_limit_enabled": true,
      "id": "01CWEEY60MREFF7PPYZ82QSQ9J",
      "max_email_recipients": 30,
      "name": "Acme",
      "subdomain": "acme"
    }
  ]
}

• user — the logged-in user’s attributes.
• teams — an array of all Teams the user belongs to, with limits and settings configured for each Team.

List Teams

Retrieve the Teams that the current user belongs to:

CLI

masv user teams

REST API

curl -X GET http://localhost:8080/api/v1/teams

Handle authentication errors

If there is no user session, or authentication failed, MASV Agent responds with a 401 Unauthorized status:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

Next steps

• Uploads — Send files via Team email, shareable Link, or Portal.
• Downloads — Initiate, monitor, and manage file downloads.
• Automations — Set up automated download and upload workflows.