API Keys

The recommended way to authorize user requests is with an API key. For other requests, like accessing packages and transfers, the MASV API requires web tokens.

API keys simplify integration with the MASV API in these ways:

• The username and password do not need to be hardcoded or stored.
• The key does not require a refresh after expiration every few days.
• An API key, while active, does not require the user to periodically answer multi-factor authentication (MFA) challenges.

Supported roles

An API key gives your application the same permissions as the MASV user from which it was created. Users with these roles can create API keys:

• Owner
• Admin
• Integration Manager

Admins and Integration Managers can manage only the API keys they create; Owners have full access to manage all API keys for the Team. To learn more about user roles and permissions, see the MASV access policy.

Create an API key

You can create and manage API keys with the MASV Web App. Authorized users can create API keys for any Team that they belong to.

Note

An API key’s value is generated automatically and returned only once. It carries the same privileges as the user that it was created for. Keep this safe and secure!

Your application can also create API keys programmatically:

Method	Route
POST	/teams/{team_id}/api_keys

Headers

Name	Type	Required	Description
X-User-Token	String	Yes	JSON Web Token. See Web Tokens.
Content-Type	String	Yes	Must be application/json

URL parameters

Name	Type	Required	Description
team_id	String	Yes	The Team ID to bind the API key to. Retrieved from authorization.

Body

Name	Type	Required	Description
name	String	No	Name of the key to create
description	String	No	Description for the key
expiry	String	No	Date-time expiry for the key. Default: 0001-01-01T00:00:00.000Z. Format: ISO 8601
state	String	Yes	State of the API key. Accepted values: active / inactive

Request

curl -d '{"name": "$NAME", "description": "$DESCRIPTION", "expiry": "$EXPIRY", "state": "$STATE"}' \
  -H "X-User-Token: $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST https://api.massive.app/v1/teams/$TEAM_ID/api_keys

Response

After a successful request, this endpoint returns 201 Created:

{
  "created_at": "2021-04-19T16:57:32.683Z",
  "description": "This is a sample API key description",
  "expiry": "2021-04-24T16:57:32.547Z",
  "id": "01F3NH1NRBQWRN7HQDJ2SYGBDH",
  "key": "<api-key-value-here>",
  "last_request_at": "0001-01-01T00:00:00.000Z",
  "name": "Sample API key",
  "state": "active",
  "updated_at": "2021-04-19T16:57:32.683Z"
}

Property	Description
created_at	The datetime that the key was created
description	The key description
expiry	The datetime the key will expire
id	The created API key ID
key	The actual API key to be used in requests to the MASV API
last_request_at	The last time the key was used
name	The name of the key
state	State of the API key. Possible values: active, inactive, suspended
updated_at	Last time key information was updated

Caution

The actual authentication key (key property) is returned only during the create response. It will not be included in any GET or LIST requests and cannot be updated. If the key is lost, a new key must be created and the old key disabled.

Note

If the Team’s account becomes inactive due to non-payment, then the Team’s API keys will be suspended until the account billing is reactivated. Attempting to use a suspended key will return error 402 unauthorized. MASV also suspends API keys when a Trial account ends. For details, see pricing.

Update API key

Users can update API keys for any Team, subject to their role.

Method	Route
PUT	/api_keys/{api_key_id}

Headers

Name	Type	Required	Description
X-User-Token	String	Yes	User JSON Web Token
Content-Type	String	Yes	Must be application/json

URL parameters

Name	Type	Required	Description
api_key_id	String	Yes	The API key to update. Use the id property, not the key property.

Body

Name	Type	Required	Description
name	String	No	Name of the key
description	String	No	Description for the key
expiry	String	No	Date-time expiry. Default: 0001-01-01T00:00:00.000Z. Format: ISO 8601
state	String	Yes	State of the API key. Accepted values: active / inactive

Request

curl -d '{"name": "$NAME", "description": "$DESCRIPTION", "expiry": "$EXPIRY", "state": "$STATE"}' \
  -H "X-User-Token: $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -X PUT https://api.massive.app/v1/api_keys/$API_KEY_ID

Response

After a successful request, this endpoint returns 200 OK:

{
  "created_at": "2021-04-19T16:57:32.683Z",
  "description": "This is a sample API key description",
  "expiry": "2021-04-24T16:57:32.547Z",
  "id": "01F3NH1NRBQWRN7HQDJ2SYGBDH",
  "last_request_at": "0001-01-01T00:00:00.000Z",
  "name": "Sample API key",
  "state": "active",
  "updated_at": "2021-04-19T16:57:32.683Z"
}

Activate/deactivate API key

Authorized users can modify the state of API keys, subject to their role. This is a helper method to quickly toggle a key’s state without fetching and passing the full object.

Method	Route
PUT	/api_keys/{api_key_id}/{action}

Headers

Name	Type	Required	Description
X-User-Token	String	Yes	User JSON Web Token
Content-Type	String	Yes	Must be application/json

URL parameters

Name	Type	Required	Description
api_key_id	String	Yes	The API key to update. Use the id property, not the key property.
action	String	Yes	State to set. Accepted values: active / inactive

Request

curl -H "X-User-Token: $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -X PUT https://api.massive.app/v1/api_keys/$API_KEY_ID/$ACTION

Response

After a successful request, this endpoint returns 204 No Content with an empty body.

If the key state is suspended, it cannot be activated or deactivated.

Delete API key

Authorized users can delete API keys, subject to their role.

Method	Route
DELETE	/api_keys/{api_key_id}

Headers

Name	Type	Required	Description
X-User-Token	String	Yes	User JSON Web Token
Content-Type	String	Yes	Must be application/json

URL parameters

Name	Type	Required	Description
api_key_id	String	Yes	The API key to delete. Use the id property, not the key property.

Request

curl -H "X-User-Token: $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -X DELETE https://api.massive.app/v1/api_keys/$API_KEY_ID

Response

After a successful request, this endpoint returns 204 No Content with an empty body.

List API keys

The Team Owner can retrieve a list of all API keys that belong to a given Team.

Method	Route
GET	/teams/{team_id}/api_keys

Headers

Name	Type	Required	Description
X-User-Token	String	Yes	User JSON Web Token
Content-Type	String	Yes	Must be application/json

URL parameters

Name	Type	Required	Description
team_id	String	Yes	The Team ID to request API keys from

Request

curl -H "X-User-Token: $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -X GET https://api.massive.app/v1/teams/$TEAM_ID/api_keys

Response

After a successful request, this endpoint returns 200 OK:

[
  {
    "created_at": "2021-04-16T20:42:37.659Z",
    "description": "This is a sample key",
    "expiry": "2021-04-20T20:42:37.000Z",
    "id": "01F3E6QN6V9TYCSRCEXB5B9JWR",
    "last_request_at": "0001-01-01T00:00:00.000Z",
    "name": "Sample key",
    "state": "active",
    "updated_at": "2021-04-19T10:42:58.221Z"
  }
]

Use an API key

API keys can be supplied in the X-API-KEY header on endpoint methods that typically require the user authorization token X-User-Token.

Example: listing sent packages

For full package documentation, see Packages.

Method	Route
GET	/teams/{team_id}/packages

curl -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -X GET https://api.massive.app/v1/teams/$TEAM_ID/packages

Endpoints that do not accept API keys

The following endpoints require X-User-Token:

Method	Route
GET	/teams/{team_id}/api_keys
PUT	/api_keys/{api_key_id}
DELETE	/api_keys/{api_key_id}
POST	/teams/{team_id}/api_keys
PUT	/users/{user_id}
POST	/users/{user_id}/password
PUT	/users/{user_id}/email