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