HTTP API Reference for Momento API Keys

Momento provides an HTTP API for managing the API keys on your account. This API lets you generate, list, refresh, and revoke API keys programmatically, without going through the Momento console.

Each API key is tied to a role, which determines what the key is allowed to do. See the Roles HTTP API for how to create and manage the roles referenced here.

Info

This is a global, account-level API served from a single endpoint: https://mga.registry.prod.a.momentohq.com.

Unlike the region-based cache endpoints, it is not tied to a specific cell or region.

Authentication

You will need a Momento API Key that grants auth-management access on your account. API Keys control access to Momento services and can be set to expire.

The API Key must be provided in the Authorization header.

Error responses

All errors share a common JSON body:

{
  "code": "Bad Request",
  "message": "A human-readable description of what went wrong."
}

Field	Type	Description
code	String	A short, machine-readable label for the error class (for example, `Bad Request`, `NotFound`, `PermissionDenied`).
message	String	A human-readable description of the error.
err	String	An optional additional error metadata string, present only for some errors.

API Keys API

The API Keys API lets you generate new API keys, list the keys that exist on your account, refresh a key, and revoke a key.

API key object

Operations that return key metadata use a common shape. The plaintext key material is never included in this object — it is returned only once, at generation time.

{
  "key_id": "api-key-id",
  "account_id": "account-id",
  "description": "For deploying to CI/CD environments",
  "role_id": "cicd-role",
  "expires_at_epoch_seconds": 1719363600,
  "issued_at_epoch_seconds": 1719360000
}

Field	Type	Description
key_id	String	The unique identifier for the key. Use this value to revoke the key.
account_id	String	The account the key belongs to.
description	String	The description supplied when the key was generated.
role_id	String	The identifier of the role that determines the key's permissions.
expires_at_epoch_seconds	Integer	When the key expires, in seconds since the Unix epoch. Omitted for keys that never expire.
issued_at_epoch_seconds	Integer	When the key was generated, in seconds since the Unix epoch.

Refresh tokens

Every expiring key is issued a refresh token alongside it, unless you opt out with exclude_refresh_token. A refresh token can be used exactly once, through Refresh API Key, for a successor key with the same role and description.

Refresh tokens are credentials and should be stored securely (e.g. in a secrets manager). They expire when the original key does, so make sure to rotate before they expire.

Generate API Key

Generates a new API key with the specified role, description, and expiry. The plaintext api_key is returned once in the response; copy it and store it securely (for example, in a secret manager such as AWS Secrets Manager, Azure Key Vault, or GCP Secret Manager). It cannot be retrieved again.

Request

Path: /api-keys
HTTP Method: POST

Headers

Header name	Required?	Type	Description
Authorization	yes	String	The Momento API key, in string format, is used for authentication/authorization of the request.
Content-Type	yes	String	Must be `application/json`.

Request Body

{
  "role_id": "cicd-role",
  "description": "For deploying to CI/CD environments",
  "expiry": 1719363600,
  "exclude_refresh_token": false
}

Field	Required?	Type	Description
role_id	yes	String	The identifier of the role to assign to the key.
description	yes	String	A human-readable description for the key.
expiry	yes	String or Integer	When the key should expire. Either the literal string `"never"`, or an integer number of seconds since the Unix epoch at which the key expires.
exclude_refresh_token	no	Boolean	Set to `true` to generate the key without a refresh token. Defaults to `false`. Keys with `"expiry": "never"` are never given a refresh token.

Responses

Success

Status Code: 200 OK

{
  "api_key": "api-key",
  "refresh_token": "refresh-token",
  "key_info": {
    "key_id": "api-key-id",
    "account_id": "account-id",
    "description": "For deploying to CI/CD environments",
    "role_id": "cicd-role",
    "expires_at_epoch_seconds": 1719363600,
    "issued_at_epoch_seconds": 1719360000
  }
}

Field	Type	Description
api_key	String	The plaintext API key. This is the only time it is returned; store it securely.
refresh_token	String	A single-use token for refreshing this key. Omitted when the key never expires or when the request set `exclude_refresh_token` to `true`. Like the API key, this is the only time it is returned; store it securely.
key_info	Object	Metadata about the generated key. See API key object.

Error

Status Code: 400 Bad Request

The request body is invalid — for example, malformed JSON, a missing field, or an expiry that is neither "never" nor an epoch-seconds integer. See the message body for further details.

Status Code: 401 Unauthorized

This error type typically indicates that the Momento API key passed in is either invalid or expired.

Status Code: 403 Forbidden

The Momento API key passed in does not grant the required access.

Status Code: 404 Not Found

No role with the specified role_id exists on the account.

Status Code: 429 Too Many Requests

The account has reached its limit on the number of API keys, or the request was throttled. Revoke a key you no longer need, or retry after a short delay.

Status Code: 500 Internal Server Error

This error type typically indicates that the service is experiencing issues. Contact Momento support for further assistance.

Refresh API Key

Exchanges a refresh token for a new API key carrying the same role and description as the key it succeeds. The plaintext api_key and the next refresh_token are both returned once; store them securely, exactly as you would a freshly generated key.

Refreshing does not revoke the key being replaced. The old key keeps working until it expires or you revoke it, which gives you a window to roll the new key out across a fleet before the old one goes away.

注意

A refresh token can be spent exactly once and must be used before the original key expires.

Request

Path: /api-keys/refresh
HTTP Method: POST

Headers

Header name	Required?	Type	Description
Authorization	yes	String	The refresh token returned from when the key was generated or last refreshed. This endpoint authenticates with the refresh token, not with an API key.
Content-Type	no	String	Must be `application/json` when a request body is sent.

Request Body

The body is optional. Send no body at all, or an empty {}, to keep the same lifetime as the original key.

{
  "expiration_epoch_seconds": 1719363600
}

Field	Required?	Type	Description
expiration_epoch_seconds	no	Integer	When the new key should expire, in seconds since the Unix epoch. It may only shorten the lifetime: it must be in the future, and no later than the time of the refresh plus the full lifetime the key being refreshed was originally issued with. When omitted, the new key gets that full lifetime measured from the time of the refresh.

Because each successor's lifetime becomes the ceiling for the refresh after it, shortening a key's lifetime here also caps every later rotation in the chain.

Responses

Success

Status Code: 200 OK

{
  "api_key": "api-key",
  "refresh_token": "refresh-token",
  "key_info": {
    "key_id": "new-api-key-id",
    "account_id": "account-id",
    "description": "For deploying to CI/CD environments",
    "role_id": "cicd-role",
    "expires_at_epoch_seconds": 1721955600,
    "issued_at_epoch_seconds": 1719363600
  },
  "previous_key_id": "api-key-id"
}

Field	Type	Description
api_key	String	The plaintext API key for the successor key. This is the only time it is returned; store it securely.
refresh_token	String	The single-use refresh token for rotating the successor key. This is the only time it is returned; store it securely.
key_info	Object	Metadata about the successor key. See API key object.
previous_key_id	String	The `key_id` of the key that was refreshed. Revoke it once the new key is in place everywhere.

Error

Status Code: 400 Bad Request

The request body is invalid — for example, malformed JSON, or an expiration_epoch_seconds that is in the past or later than the original key's lifetime allows. See the message body for further details.

Status Code: 401 Unauthorized

The credential in the Authorization header is missing, malformed, expired, or is not a refresh token. An API key or session token cannot be used here and a refresh token cannot be used on any other endpoint. This status is also returned when the key the token refreshes has been revoked.

Status Code: 403 Forbidden

The refresh token has already been used or the account is locked.

Status Code: 429 Too Many Requests

The account has reached its limit on the number of API keys or the request was throttled. When the key limit is the cause, the refresh token is not spent — revoke a key you no longer need and retry with the same token.

Status Code: 500 Internal Server Error

This error type typically indicates that the service is experiencing issues. Contact Momento support for further assistance.

List API Keys

Lists the API keys on your account, with pagination. The plaintext key material is never returned.

Request

Path: /api-keys
HTTP Method: GET

Query Parameters

Parameter name	Required?	Type	Description
limit	no	Integer	The maximum number of keys to return in a single page. Must be between 1 and 100, inclusive. Defaults to 100 when omitted.
next_token	no	String	The pagination token returned by a previous call. Omit it to fetch the first page.

Headers

Header name	Required?	Type	Description
Authorization	yes	String	The Momento API key, in string format, is used for authentication/authorization of the request.

Responses

Success

Status Code: 200 OK

{
  "key_info": [
    {
      "key_id": "api-key-id-1",
      "account_id": "account-id",
      "description": "For deploying to CI/CD environments",
      "role_id": "cicd-role",
      "expires_at_epoch_seconds": 1719363600,
      "issued_at_epoch_seconds": 1719360000
    },
    {
      "key_id": "api-key-id-2",
      "account_id": "account-id",
      "description": "Read-only access for the metrics dashboard",
      "role_id": "analytics-readonly-role",
      "issued_at_epoch_seconds": 1719000000
    }
  ],
  "next_token": "next-token"
}

Field	Type	Description
key_info	Array	The API keys on the account for this page. Each entry has the shape described in API key object.
next_token	String	A pagination token for fetching the next page. Present only when more keys are available; pass it as the `next_token` query parameter on the next call.

Error

Status Code: 400 Bad Request

The query parameters are invalid — for example, a non-numeric limit, or a limit outside the range 1 to 100. See the message body for further details.

Status Code: 401 Unauthorized

This error type typically indicates that the Momento API key passed in is either invalid or expired.

Status Code: 403 Forbidden

The Momento API key passed in does not grant the required access.

Status Code: 429 Too Many Requests

The request was throttled. Retry after a short delay.

Status Code: 500 Internal Server Error

This error type typically indicates that the service is experiencing issues.

Revoke API Key

Revokes an API key, disabling it immediately.

Request

Path: /api-keys/{key_id}
HTTP Method: DELETE

Path Parameters

Parameter name	Required?	Type	Description
key_id	yes	String	The identifier of the key to revoke.

Headers

Header name	Required?	Type	Description
Authorization	yes	String	The Momento API key, in string format, is used for authentication/authorization of the request.

Responses

Success

Status Code: 200 OK

{}

The key has been revoked. The response body is an empty object.

Error

Status Code: 401 Unauthorized

This error type typically indicates that the Momento API key passed in is either invalid or expired.

Status Code: 403 Forbidden

The Momento API key passed in does not grant the required access.

Status Code: 404 Not Found

No key with the specified key_id exists on the account.

Status Code: 429 Too Many Requests

The request was throttled. Retry after a short delay.

Status Code: 500 Internal Server Error

This error type typically indicates that the service is experiencing issues.

Examples

Example: Generate an API Key

Generate a key that never expires:

curl -X POST -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": "cicd-role",
    "description": "For deploying to CI/CD environments",
    "expiry": "never"
  }' \
  "https://mga.registry.prod.a.momentohq.com/api-keys"

Generate a key that expires at a specific time (seconds since the Unix epoch). The response also carries a refresh_token for rotating it later:

curl -X POST -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": "cicd-role",
    "description": "Temporary key for the Q3 data migration",
    "expiry": 1719363600
  }' \
  "https://mga.registry.prod.a.momentohq.com/api-keys"

Generate an expiring key that cannot be rotated by opting out of the refresh token:

curl -X POST -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": "cicd-role",
    "description": "Temporary key for the Q3 data migration",
    "expiry": 1719363600,
    "exclude_refresh_token": true
  }' \
  "https://mga.registry.prod.a.momentohq.com/api-keys"

Example: Refresh an API Key

Rotate a key, giving the successor the same lifetime the original was issued with. The refresh token goes in the Authorization header and no body is needed:

curl -X POST -H "Authorization: <refresh-token>" \
  "https://mga.registry.prod.a.momentohq.com/api-keys/refresh"

Rotate a key and give the successor a shorter lifetime:

curl -X POST -H "Authorization: <refresh-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "expiration_epoch_seconds": 1719363600
  }' \
  "https://mga.registry.prod.a.momentohq.com/api-keys/refresh"

Once the new key is deployed everywhere, revoke the key it replaced using the previous_key_id from the refresh response:

curl -X DELETE -H "Authorization: <token>" \
  "https://mga.registry.prod.a.momentohq.com/api-keys/previous-key-id"

Example: List API Keys

Fetch the first page of keys:

curl -H "Authorization: <token>" \
  "https://mga.registry.prod.a.momentohq.com/api-keys?limit=50"

Fetch the next page using the token from a previous response:

curl -H "Authorization: <token>" \
  "https://mga.registry.prod.a.momentohq.com/api-keys?limit=50&next_token=next-token"

Example: Revoke an API Key

Revoke a key by its key_id:

curl -X DELETE -H "Authorization: <token>" \
  "https://mga.registry.prod.a.momentohq.com/api-keys/api-key-id"

Authentication​

Error responses​

API Keys API

API key object​

Refresh tokens​

Generate API Key​

Request​

Headers​

Request Body​

Responses​

Success​

Error​

Refresh API Key​

Request​

Headers​

Request Body​

Responses​

Success​

Error​

List API Keys​

Request​

Query Parameters​

Headers​

Responses​

Success​

Error​

Revoke API Key​

Request​

Path Parameters​

Headers​

Responses​

Success​

Error​

Examples

Example: Generate an API Key​

Example: Refresh an API Key​

Example: List API Keys​

Example: Revoke an API Key​

Authentication

Error responses

API key object

Refresh tokens

Generate API Key

Request

Headers

Request Body

Responses

Success

Error

Refresh API Key

Request

Headers

Request Body

Responses

Success

Error

List API Keys

Request

Query Parameters

Headers

Responses

Success

Error

Revoke API Key

Request

Path Parameters

Headers

Responses

Success

Error

Example: Generate an API Key

Example: Refresh an API Key

Example: List API Keys

Example: Revoke an API Key