Skip to content

API Keys

The MASV API allows users to create and manage keys that may be used as authorization for requests to the API. These API Keys may be 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 need not be hard-coded; and 2) there isn't a token that necessarily expires and requires a refresh every few days.

API Keys are only supported on user-bound methods, meaning that they can only be used as a replacement on 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.

For now, only Team Owners have permission to manage API Keys for the Team.

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.

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.

POST /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
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 - by default keys do not expire
state String Yes State of the API key - can be set to active or inactive
REQUEST
curl -H "X-User-Token: $USER_TOKEN" -H "Content-Type: application/json" -X POST https://api.massive.app/v1/teams/$TEAM_ID/api_keys -d '{"name": "$NAME", "description": "$DESCRIPTION", "expiry": "$EXPIRY", "state": "$STATE"}'

Where:

  • $USER_TOKEN is the auth token returned during auth request (refer to Authorization: Login section of this document)
  • $TEAM_ID is the team ID returned during auth request (refer to Authorization: Login section of this document)
  • $NAME is the name of the key
  • $DESCRIPTION is a description of the key
  • $EXPIRY is the date-time string that the key will expire and no longer be accepted (ie. "2021-01-01T00:00:00.000Z")
  • $STATE indicates if the key can be used (active) or not (inactive)

After a successful request where an API key has been created, this endpoint will return an HTTP response with a status code of 201 Created and a body similar to the one 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"
}

Where:

  • id is the created API key ID.
  • key is the actual API key to be used in requests to the MASV API

Note

The actual key is only returned in the create response and will not be included in any Get or List requests. It cannot be updated - a new key can be created and old keys can be disabled or deleted.

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.

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
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 - by default keys do not expire
state String Yes State of the API key - can be set to active or 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 -d '{"name": "$NAME", "description": "$DESCRIPTION", "expiry": "$EXPIRY", "state": "$STATE"}'

Where:

  • $USER_TOKEN is the auth token returned during auth request (refer to Authorization: Login section of this document)
  • $API_KEY_ID is the key ID returned during auth request
  • $NAME is the name of the key
  • $DESCRIPTION is a description of the key
  • $EXPIRY is the date-time string to be used as the new expiration (ie. "2021-01-01T00:00:00.000Z")
  • $STATE indicates if the key can be used (active) or not (inactive)

After a successful request where an API key has been updated, this endpoint will return an HTTP response with a status code of 200 OK and a body similar to the one 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"
}

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.

  • PUT api_keys/{{api_key_id}}/activate
  • PUT api_keys/{{api_key_id}}/deactivate
HEADERS
Name Type Required Description
X-User-Token String Yes User JSON Web Token
Content-Type String Yes Must be application/json
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

Where:

  • $USER_TOKEN is the auth token returned during auth request (refer to Authorization: Login section of this document)
  • $API_KEY_ID is the key ID returned during auth request
  • $ACTION is activate or deactivate to signal what the new state should be

After a successful request where an API key has been updated, this endpoint will 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 was suspended it cannot be activated or deactivated.

Delete API Key

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

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

Where:

  • $USER_TOKEN is the auth token returned during auth request (refer to Authorization: Login section of this document)
  • $API_KEY_ID is the key ID returned during creation

After a successful deletion request, this endpoint will return an HTTP response with a status code of 204 No Content and an empty body. Any API requests that include the API Key in the headers will be rejected with error 401 unauthorized.

List API Keys

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

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
REQUEST
curl -H "X-User-Token: $USER_TOKEN" -H "Content-Type: application/json" -X DELETE https://api.massive.app/v1/teams/$TEAM_ID/api_keys

Where:

  • $USER_TOKEN is the auth token returned during auth request (refer to Authorization: Login section of this document)
  • $TEAM_ID is the team ID returned during auth request (refer to Authorization: Login section of this document)

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

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

Sample - List Team Portals

GET /teams/{team_id}/portals

HEADERS
Name Type Required Description
X-API-KEY String Yes API Key value
REQUEST
curl -H `X-API-KEY: $API_KEY` -X GET https://api.massive.app/v1/teams/$TEAM_ID/portals

User Methods That Do Not Accept API Keys

The following User methods will continue to require X-User-Token:

  • GET /api_keys/{api_key_id}
  • 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