メインコンテンツまでスキップ

Manage Momento Roles

Momento provides a CLI and an HTTP API for managing the roles on your account. A role is a named set of permissions that you assign to account members and API keys to control what they can do.

This page contains brief explanations of necessary terms. See roles and permissions to learn more about concepts related to authentication, including permission sets, roles, and how credentials bind permissions.

There are two kinds of role:

  • System roles are the built-in roles Momento provides (such as Owner, Operator, and Viewer). They cannot be modified or deleted.
  • Custom roles are roles you define, with a fine-grained permission set that you control. This API lets you create, update, list, and delete custom roles.
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 v2 Momento API Key that grants auth-management access on your account. API Keys control access to Momento services and can be set to expire.

Our Momento roles API (and roles CLI) does not accept disposable tokens or legacy API Keys.

The CLI will use your default profile (created via momento configure), or you can specify a --profile.

Error responses​

All errors share a common JSON body:

{
  "code": "Bad Request",
  "message": "A human-readable description of what went wrong."
}
FieldTypeDescription
codeStringA short, machine-readable label for the error class (for example, Bad Request, NotFound, PermissionDenied).
messageStringA human-readable description of the error.
errStringAn optional additional error metadata string, present only for some errors.

The CLI formats these errors in plaintext for you.

Role object​

Every role is represented by the same JSON shape:

{
  "role_id": "r-12345",
  "role_name": "analytics-readonly-role",
  "role_type": "custom",
  "description": "Read-only access for the analytics team",
  "permissions": {
    "rules": [
      {
        "type": "cache",
        "permissions": ["read", "list"],
        "caches": "*",
        "items": "*"
      }
    ]
  }
}
FieldTypeDescription
role_idStringThe unique identifier for the role. Use this value to update or delete a custom role, or to assign the role to an API key.
role_nameStringThe human-readable name of the role.
role_typeStringEither system (built-in) or custom (user-defined).
descriptionStringAn optional description of the role. Omitted when the role has no description.
permissionsObjectThe role's permission set. See Permission set.

The CLI formats the role object in plaintext for you.

Permission set​

A permission set describes exactly what a role is allowed to do. It is a list of rules, plus optional conditions that constrain when the permissions apply:

{
  "rules": [ /* one or more rule objects */ ],
  "conditions": [ /* zero or more condition objects */ ]
}
FieldRequired?TypeDescription
rulesyesArrayThe permission rules that make up the role. See Rules.
conditionsnoArrayAdditional constraints that apply to the whole permission set. See Conditions. Defaults to an empty list.

Rules​

Each rule is an object tagged by a type field. The other fields depend on the type. Every rule carries a permissions array; the valid permission values depend on the rule type.

Rule typeValid permissionsOther fields
account_managementread, list—
auth_managementread, write, listitems (must be "*")
resource_managementread, write, listresources (must be "*")
databaseread, writedatabases, items
cacheread, write, listcaches, items
topicread, write, listcaches, topics
storeread, write, liststores, items
functioninvokecaches, functions

Selectors​

The databases, caches, stores, topics, functions, and items fields are selectors. A selector is either the wildcard string "*" (meaning "all"), or an object that names a specific resource:

SelectorWildcardObject formsUsed by
Name"*"{ "name": "my-cache" }databases, caches, stores
Name or prefix"*"{ "name": "my-topic" } or { "prefix": "room-" }topics, functions
Item"*"{ "key": "my-key" } or { "key_prefix": "public/" }database/cache/store items

The items field on an auth_management rule and the resources field on a resource_management rule must always be the wildcard "*".

A Database rule's permissions array contains "read", "write", or both.

Rule examples​

Full access to all caches and their items:

{ "type": "cache", "permissions": ["read", "write", "list"], "caches": "*", "items": "*" }

Read-only access to keys under a prefix in a single cache:

{
  "type": "cache",
  "permissions": ["read"],
  "caches": { "name": "prod-cache" },
  "items": { "key_prefix": "public/" }
}

Read and write access to all Momento Cache Databases and their items:

{
  "type": "database",
  "permissions": ["read", "write"],
  "databases": "*",
  "items": "*"
}

Read-only access to all keys under a prefix in a single named Database:

{
  "type": "database",
  "permissions": ["read"],
  "databases": { "name": "orders" },
  "items": { "key_prefix": "orders:2026-" }
}

Publish to all topics whose name starts with room- in one cache:

{
  "type": "topic",
  "permissions": ["write"],
  "caches": { "name": "chat-app" },
  "topics": { "prefix": "room-" }
}

Invoke a single function:

{
  "type": "function",
  "permissions": ["invoke"],
  "caches": { "name": "edge-app" },
  "functions": { "name": "resize-image" }
}

Conditions​

Conditions constrain when the permission set applies. Currently the only supported condition is an ip_filter, which restricts requests to a set of allowed CIDR ranges (IPv4 or IPv6):

{
  "ip_filter": {
    "allowed_cidr_ranges": ["10.0.0.0/8", "192.168.1.0/24", "2001:db8::/32"]
  }
}
FieldTypeDescription
ip_filter.allowed_cidr_rangesArray<String>The CIDR ranges from which requests are allowed. Each entry must be a valid CIDR range, including a prefix length (for example, 10.0.0.0/8, not 10.0.0.1).

Full permission set example​

The following permission set exercises every rule type, selector variant, and the IP filter condition:

{
  "rules": [
    { "type": "account_management",  "permissions": ["read", "list"] },
    { "type": "auth_management",     "permissions": ["read", "write", "list"], "items": "*" },
    { "type": "resource_management", "permissions": ["read", "write", "list"], "resources": "*" },
    { "type": "database", "permissions": ["read", "write"],         "databases": "*",                  "items": "*" },
    { "type": "database", "permissions": ["read"],                  "databases": { "name": "orders" }, "items": { "key_prefix": "orders:2026-" } },
    { "type": "database", "permissions": ["write"],                 "databases": { "name": "orders" }, "items": { "key": "orders:pending" } },
    { "type": "cache",    "permissions": ["read", "write", "list"], "caches": "*",                    "items": "*" },
    { "type": "cache",    "permissions": ["read"],                  "caches": { "name": "prod-cache" }, "items": { "key_prefix": "public/" } },
    { "type": "cache",    "permissions": ["write"],                 "caches": { "name": "prod-cache" }, "items": { "key": "feature-flags" } },
    { "type": "topic",    "permissions": ["read", "write", "list"], "caches": "*",                    "topics": "*" },
    { "type": "topic",    "permissions": ["read"],                  "caches": { "name": "chat-app" },  "topics": { "name": "announcements" } },
    { "type": "topic",    "permissions": ["write"],                 "caches": { "name": "chat-app" },  "topics": { "prefix": "room-" } },
    { "type": "store",    "permissions": ["read", "write", "list"], "stores": "*",                    "items": "*" },
    { "type": "store",    "permissions": ["read"],                  "stores": { "name": "user-prefs" }, "items": { "key_prefix": "org:42:" } },
    { "type": "store",    "permissions": ["write"],                 "stores": { "name": "user-prefs" }, "items": { "key": "schema-version" } },
    { "type": "function", "permissions": ["invoke"],                "caches": "*",                    "functions": "*" },
    { "type": "function", "permissions": ["invoke"],                "caches": { "name": "edge-app" }, "functions": { "name": "resize-image" } },
    { "type": "function", "permissions": ["invoke"],                "caches": { "name": "edge-app" }, "functions": { "prefix": "webhook-" } }
  ],
  "conditions": [
    { "ip_filter": { "allowed_cidr_ranges": ["10.0.0.0/8", "192.168.1.0/24", "2001:db8::/32"] } }
  ]
}

Roles Management

The Roles API and CLI let you list the roles on your account and create, update, and delete custom roles.

List Roles​

Lists the roles on your account, with pagination.

Request​

momento role list

The CLI lists only your custom roles. (To list system roles, use the HTTP API.)

You can --limit how many custom roles are fetched on each page:

momento role list --limit 5
  • --limit must be between 1 and 100, inclusive. Defaults to 100 when omitted.

Responses​

Success​

Name: cicd-role
ID: r-abcdefg
Description: For deploying to CI/CD environments
Rules:
- Cache: prod-cache
  Keys: all
  Allowed actions: Read, Write
Conditions: (none)

Name: analytics-readonly-role
ID: r-12345
Description: Read-only access for the analytics team
Rules:
- Caches (all)
  Keys: all
  Allowed actions: Read, List
Conditions: (none)

View more? [y]

The CLI will prompt you until it's listed all your roles.

Error​

Status Code: 400 Bad Request

  • The query parameters are invalid — for example, a limit outside the range 1 to 100, or an unrecognized type. 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.

Create Custom Role​

Creates a new custom role with the specified permission set.

Request​

momento role create --name cicd-role \
  --description "For deploying to CI/CD environments" \
  --permission-set '{
    "rules": [
      {
        "type": "cache",
        "permissions": ["read", "write"],
        "caches": { "name": "prod-cache" },
        "items": "*"
      }
    ]
  }'
ArgumentRequired?TypeDescription
nameyesStringA human-readable name for the role.
descriptionnoStringAn optional description of the role.
permission-setyesObjectThe role's permission set. See Permission set.

Responses​

Success​

Creating custom role!

Name: cicd-role
ID: r-abcdefg
Description: For deploying to CI/CD environments
Rules:
- Cache: prod-cache
  Keys: all
  Allowed actions: Read, Write
Conditions: (none)

Error​

Status Code: 400 Bad Request

  • The request body contains an invalid permission set or an invalid CIDR range. 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: 409 Already Exists

  • A role with the specified name already exists.

Status Code: 429 Too Many Requests

  • Either the request was throttled (retry after a short delay), or your account has reached its maximum number of custom roles (delete an existing custom role before creating a new one).

Status Code: 500 Internal Server Error

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

Update Custom Role​

Updates an existing custom role's name, description, and/or permission set. System roles cannot be updated.

Request​

Specify the role by its current name:

momento role update --name cicd-role \
  --description "For deploying to CI/CD environments across all caches" \
  --permission-set '{
    "rules": [
      {
        "type": "cache",
        "permissions": ["read", "write"],
        "caches": "*",
        "items": "*"
      }
    ]
  }'

Or you can specify the role by its ID:

momento role update --id r-abcdefg \
  --description "For deploying to CI/CD environments across all caches" \
  --permission-set '{
    "rules": [
      {
        "type": "cache",
        "permissions": ["read", "write"],
        "caches": "*",
        "items": "*"
      }
    ]
  }'
ArgumentRequired?TypeDescription
nameyes (or id)StringThe current name for the role.
idyes (or name)StringThe ID for the role.
renamenoStringThe new name for the role. If omitted, the role's existing name is left unchanged.
descriptionnoStringThe new description for the role. If omitted, the role's existing description is left unchanged.
permission-setnoObjectThe new permission set for the role. See Permission set. If omitted, the role's existing permission set is left unchanged.

Responses​

Success​

Updating custom role!

Name: cicd-role
ID: r-abcdefg
Description: For deploying to CI/CD environments across all caches
Rules:
- Caches (all)
  Keys: all
  Allowed actions: Read, Write
Conditions: (none)

Error​

Status Code: 400 Bad Request

  • The request body contains an invalid permission set or an invalid CIDR range.

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 custom role with the specified role_id exists on the account.

Status Code: 412 Precondition Failed

  • The specified role is a system role, which cannot be updated.

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.

Delete Custom Role​

Deletes a custom role. A role can only be deleted once nothing references it. If the role is still assigned to any account members, pending invitations, or API keys, the delete is blocked and the response lists what is still using it. System roles cannot be deleted.

Request​

momento role delete --name cicd-role

Or you can specify the role by its ID:

momento role delete --id r-abcdefg

Responses​

Success​

When the role was deleted:

Deleted custom role cicd-role (ID r-abcdefg)!

Error​

When the delete was blocked because the role is still in use, the response lists every member, invitation, and API key that still references it:

ERROR: Couldn't delete custom role cicd-role (ID r-abcdefg) because it's still in use:

Account Members:
- jane@example.com
Invited Account Members:
- sam@example.com
API Keys:
- Key ID: api-key-id
  Account ID: account-id
  Description: For deploying to CI/CD environments
  Issued At: 2024-06-26 00:00:00 UTC

To delete a blocked role, reassign or remove everything listed in the response, then retry the delete.

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 custom role with the specified role_id exists on the account.

Status Code: 412 Precondition Failed

  • The specified role is a system role, which cannot be deleted.

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: List Roles​

List only the custom roles on your account:

momento role list --limit 50

Example: Create a Custom Role​

Create a role with read/write access to a single cache:

momento role create --name cicd-role \
  --description "For deploying to CI/CD environments" \
  --permission-set '{
    "rules": [
      {
        "type": "cache",
        "permissions": ["read", "write"],
        "caches": { "name": "prod-cache" },
        "items": "*"
      }
    ]
  }'

Example: Update a Custom Role​

Broaden the role to cover all caches:

momento role update --name cicd-role \
  --permission-set '{
    "rules": [
      {
        "type": "cache",
        "permissions": ["read", "write"],
        "caches": "*",
        "items": "*"
      }
    ]
  }'

Or you can specify the role by its ID:

momento role update --id r-abcdefg \
  --permission-set '{
    "rules": [
      {
        "type": "cache",
        "permissions": ["read", "write"],
        "caches": "*",
        "items": "*"
      }
    ]
  }'

Example: Rename a Custom Role​

Specify the role by its current name:

momento role update --name cicd-role --rename cache-manager

Or you can specify the role by its ID:

momento role update --id r-abcdefg --rename cache-manager

Example: Delete a Custom Role​

Delete a role by its name or ID:

momento role delete --name cicd-role
momento role delete --id r-abcdefg