Skip to content

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:

  1. The username and password does not need to be hardcoded or stored.
  2. 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 -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.

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

{
    "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 \
-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 \
-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 \
-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.

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