Skip to main content

Permissions

Last updated on

Overview​

Permissions are the mechanism used to grant access rights to specific resources within our services. Most AccelByte Cloud service endpoints require a permission to access. Our API Documentation lists the permission required for each endpoint, and we also maintain a working list of permission tags for each endpoint, grouped by service.

Permissions are used to filter all access to their respective endpoints, whether it be from users or applications. In the Admin Portal, permissions can be assigned to Clients to determine which endpoints applications and players can access, or to Roles to determine not only which endpoints users can access, but also which features users can access in the Admin Portal itself. So if a user does not have a role that allows them to ban users, they will not see that menu when they log into the Admin Portal.

Resources​

Resources are what permissions are applied to; they are what permissions protect. An example of a resource would be an endpoint URL, such as:

/lobby/v1/public/party/namespaces/{namespace}/parties/{partyId}/attributes

There may be multiple permissions that apply to the same resource, but require different actions. Each endpoint requires a unique permission string.

Sources​

Permissions can be defined in several places, depending on which users you want to provide the permission to.

  • Permissions defined on a Role apply to all users assigned that role. Information about assigning permissions to roles can be found in the Role Management documentation.
  • Permissions defined on an IAM Client apply when a client performs an action that isn't on behalf of a user, such as a dedicated server storing the result of a match and marking the top scoring player as MVP. Information about assigning permissions to clients can be found in the IAM Clients documentation.

Syntax​

A permission consists of a permission tag and permission action.

The permission tag is a string containing multiple tokens, delimited by colons. Permission tags can include details like the namespace and user that the permission applies to, as well as the name of the guarded resource.

Permission actions describe what the permission allows a user or application to do to a resource. The supported actions are Create, Read, Update, and Delete.

Here's a template of a permission tag:

[ADMIN]:NAMESPACE:namespace:USER:userid:RESOURCENAME

  • ADMIN This optional token indicates that the permission is intended for administrative resources and is only used for informative purposes to allow role managers to more easily identify which roles are able to access administrative functionalities.

  • NAMESPACE:namespace This token works like a key/value pair and indicates which namespace the permission applies to. The syntax is the literal string NAMESPACE: followed by either {namespace}, a wildcard (*), or a specific namespace name.

    • {namespace}: This token value tells the backend to dynamically bind to the user's current logged-in namespace, replacing {namespace} with the name of the actual namespace from the granted token.

      If the token is granted in namespaceA, then {namespace} will resolve to namespaceA, and this part of the permission tag will be replaced with NAMESPACE:namespaceA.

    • Specific namespace name: If a specific namespace is specified (e.g., NAMESPACE:namespaceA), the permission is granted only within that specific namespace. This can be used, for example, by publishers to provide a way to give admin access to users for a specific game within the publisher's namespace.

    • *: An asterisk is interpreted as a wildcard, allowing access to that resource in all namespaces.

  • USER:userid This token works similarly to the NAMESPACE token: it is a key/value pair that represents which user the permission applies to. These tokens are only used for resources which are user-specific.

    The syntax is the literal string USER: followed by either {userId}, a wildcard (*), or a specific user ID.

    • {userId}: This token value tells the backend to dynamically bind to the logged-in user's ID, replacing {userId} with the user's actual ID.

      If the logged in user's ID is 1234, then {userId} will resolve to 1234, and this part of the permission tag will be replaced with USER:1234.

    • Specific user ID: If a specific user ID is specified, the permission is granted only for that specific user.

    • *: An asterisk is interpreted as a wildcard, allowing access to that resource for any user ID.

  • RESOURCENAME This token represents the guarded resource, such as PROFILE or CURRENCY. Permission tags can contain more than one resource name, delimited by colons (e.g., PAYMENT:NOTIFICATION).

    If you want to match any resource after userid, replace the resource name with a wildcard (e.g., **[ADMIN]:NAMESPACE:namespace:USER:userid:_)._**

tip

There are hundreds of valid permission tags in our Cloud platform. To keep it simple, we keep a working list of all of the permission tags that you can easily copy and paste from.

caution

Some endpoints may not follow the syntax outlined above. To confirm a permission string's syntax, follow the steps below.

Finding an Endpoint's Permission​

You can see the permission of an endpoint in the AccelByte API Documentation.

  1. On the page linked above, click the service for which you need permission.

  2. In the Platform APIs page of the selected service, click one of the sub-services to expand the list of available endpoints.

  1. Browse the list of endpoints until you find the one you need, and then click to expand it.

  1. You can see the required permission for the selected endpoint along with its resource and action near the top of the documentation for your endpoint.