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
Integration Manager

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

A 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	Required Value: `application/json`

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` Accepted Format: ISO 8601
`state`	String	Yes	State of the API key Accepted Values: `active`/`inactive`

URL parameters

Name	Type	Required	Description
`team_id`	String	Yes	The team id to bind the api key. (Retrieved in (Generate))

REQUEST

curl

    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

After a successful request an API key will be created, the endpoint will return an HTTP response with a status code of 201 Created and a body response matching the json below.

Example JSON Response

{
    "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"
}

Response Properties:

Property	Description
`created_at`	The datetime that the key was created.
`description`	The key description (provided in the previous step).
`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 (provided in the previous step).
`state`	State of the API key Possible Values: `active`, `inactive`, `suspended`.
`updated_at`	Last time key information was updated.

Warning

The actual authentication key property: key is returned during the create response. It will not be included in any Get or List requests. It is unable to be updated. In case of they key being lost, a new key will need to be created and the old key disabled.

Important

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 that they are authorized to. (access policy).

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

HEADERS

Name	Type	Required	Description
`X-User-Token`	String	Yes	User JSON Web Token (Generate)
`Content-Type`	String	Yes	Required Value: `application/json`

URL parameters

Name	Type	Required	Description
`api_key_id`	String	Yes	The API key to be updated. Ref `property: id` above. Not `property: key`

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` Accepted Format: ISO 8601
`state`	String	Yes	State of the API key Accepted Values: `active`/`inactive`

REQUEST

curl

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

After a successful request the API key will be updated. This endpoint will then return an HTTP response with a status code of 200 OK and a body response matching the json below.

If the key state has been set to inactive then any API requests that use the key in the headers will be rejected with error 401 unauthorized.

Example JSON Response

{
    "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"
}

Response Properties:

Property	Description
`created_at`	The datetime that the key was created.
`description`	The key description (provided in the previous step.)
`expiry`	String
`id`	The created API key ID.
`last_request_at`	The last time the key was used.
`name`	The name of the key (provided in the previous step.)
`state`	State of the API key Possible Values: `active`/`inactive`
`updated_at`	Last time key information was updated.

Warning

As mentioned above the actual authentication key property: key is returned during the create response. It will not be included in any Get or List requests. It is unable to be updated. In case of they key being lost, a new key will need to be created and the old key disabled.

Activate/deactivate API key

Authorized users can modify the state of any of their Team's API keys. This serves as a helper method to quickly toggle a key's state without having to fetch and pass the full object. (access policy).

Method	Route
`PUT`	`/api_keys/{{ api_key_id }}/{{ state }}`

HEADERS

Name	Type	Required	Description
`X-User-Token`	String	Yes	User JSON Web Token (Generate)
`Content-Type`	String	Yes	Required Value: `application/json`

URL parameters

Name	Type	Required	Description
`api_key_id`	String	Yes	The API key to be updated. Ref `property: id` above. Not `property: key`
`action`	String	Yes	State of the API key to be updated Accepted Values: `active`/`inactive`

REQUEST

curl

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

After a successful request the API key will be updated. This endpoint will then return an HTTP response with a status code of 204 No Content and an empty body.

If the key state has been set to inactive then any API requests that use the key in the headers will be rejected with error 401 unauthorized.

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

Delete API key

Authorized users can delete API keys. (access policy).

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 be updated. Ref `property: id` above. Not `property: key`

REQUEST

curl

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

After a successful request the API key will be deleted. The endpoint will then return an HTTP response with a status code of 204 No Content and 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. (Retrieved in (Generate))

REQUEST

curl

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

After a successful request, 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

[
    {
        "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"
    },
    {
        "created_at": "2021-04-16T19:29:46.381Z",
        "description": "This is a sample key that has been set to inactive",
        "expiry": "0001-01-01T00:00:00.000Z",
        "id": "01F3E2J8CDDM4XDXE8RRFWWCXY",
        "last_request_at": "2021-04-18T11:23:48.223Z",
        "name": "Inactive sample key",
        "state": "inactive",
        "updated_at": "2021-04-19T10:42:58.200Z"
    }
]

Use an API key

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

Sample: Listing sent packages

For full package documentation please reference Document: Packages

GET /teams/{{ team_id }}/packages

HEADERS

Name	Type	Required	Description
`X-API-KEY`	String	Yes	API key value
`Content-Type`	String	Yes	Must be `application/json`

REQUEST

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

User methods that do not accept API keys

The following User methods require X-User-Token:

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