API Keys

The MASV API allows users to create and manage keys that are used as authorization for requests to the API. These API Keys are used in place of a traditional User Token in the headers of the request.

This simplifies integration with the MASV API in two ways:

The username and password does not need to be hardcoded or stored.
The token does not require a refresh after expiration every few days.

API Keys are only supported on user-bound methods. Compatible with routes and functions that require X-User-Token. All other endpoints which use alternate tokens (ie. X-Package-Token or X-Transfer-Token) remain unchanged and will still require those authorization methods.

Note

API Keys cannot be used on requests to manage API Keys or modify user profile details (ie. change password or email) - these will continue to require X-User-Token.

Warning

Only Team Owners have permission to manage API Keys for the Team.

Create API Key

Team Owners can create API Keys for any team that they own. The value for the key is generated automatically and returned only once in the initial response. Afterwards it is impossible to retrieve the key's value again.

Method	Route
`POST`	`/teams/{{ team_id }}/api_keys`

HEADERS

Name	Type	Required	Description
`X-User-Token`	String	Yes	User JSON Web Token (Generate)
`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`
`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 subscription becomes inactive or the trial ends, then API keys will be suspended until the team is reactivated. Attempting to use a suspended key will return error 402 unauthorized

Update API Key

Team Owners can update API Keys for any team that they own.

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

Team Owners can modify an API Key's state for any team that they own. This serves as a helper method to quickly toggle a Key's state without having to fetch and pass the full object.

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

Team Owners can delete API Keys for any team that they own.

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

Using 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 will continue to 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`