Master permissions

Last updated on December 17, 2024

Introduction

Permissions provide access rights to users and applications that use AccelByte Gaming Service (AGS) resources. They are the cornerstone of the authorization system, which includes these parts:

1. Permission requirement: most AGS API endpoints require permissions.

   note

   Our API Endpoint documentation lists the permissions the system requires for each endpoint.

2. Permission grant: using the Admin Portal, you can assign permissions to your applications via IAM Clients, and to your users via Roles.

This article provides a detailed breakdown of AGS permissions and their respective use. Links to related guides that demonstrate permission you can assign via IAM Clients and roles to your users are also provided.

Syntax

Permissions consist of a permission resource and a permission action.

Permission Resource

We use RESTful API design for AccelByte Gaming Services (AGS). In the RESTful API, the primary data representation is a resource. In AGS, the permission resource is a string containing multiple tokens, delimited by colons. It can include details like the namespace and user that the permission applies to, as well as the name of the guarded objects.

Permission Action

Permission Actions describe what the permission enables a user or application to do with a resource. Actions are: Create, Read, Update, and Delete.

Permission Requirement

Follow the general syntax described above when you define the permission for an AGS endpoint. For example, here's a template of a permission requirement for an AGS endpoint, which includes four separate tokens:

[ADMIN:][NAMESPACE:<namespace>:][USER:<userId>:]<OBJECTNAME>

• ADMIN: An optional token that indicates the permission is for administrative resources. It should only be prefixed in permissions for ADMIN endpoints and is for use in these scenarios:

  • Trusted internal API calls between AGS and your applications, which IAM Clients authorizes.
  • An Admin user with the correct Role can perform calls using the Admin Portal (or another suitable external tool).

  For example, users need admin permission for the endpoint they use to search for role information:

  Endpoint	Permission	Description
  GET /iam/v3/admin/roles	ADMIN:ROLE <READ>	Since Role is a platform level object that does not belong to any namespace or user, the permission doesn't contain a Namespace:{namespace} or User:{userid}.

  • Public endpoints always use non-admin permissions. Any authorized user account with a valid access token can call these endpoints.

• NAMESPACE:{namespace}, Use this optional token only if the resource is under a namespace level, which the IAM Client, Store, and other resources require. It indicates which namespace the permission applies to. The syntax is the string NAMESPACE: with a namespace name placeholder {namespace} following. For example, users need admin permission for an endpoint that creates an IAM Client within a specific namespace:

  Endpoint	Permission	Description
  POST /iam/v3/admin/namespaces/{namespace}/clients	ADMIN:NAMESPACE:{namespace}:CLIENT <CREATE>	When a request tries to access a resource via: POST /iam/v3/admin/namespaces/accelbyte/clients, the permission is ADMIN:NAMESPACE:accelbyte:CLIENT [CREATE]. As an IAM Client is under namespace level but not a user-specific resource, there is no User:userId in the permission.

• USER:{userId}: Use this optional token for user-specific resources only. This token is similar to NAMESPACE:{namespace part}, and represents the user the permission applies to. The syntax is USER: with a user id placeholder {userid} following. For example, this is an admin permission required for an endpoint that is used to search for the entitlements that belong to a specific user in a specific namespace:

  Endpoint	Permission	Description
  GET /admin/namespaces/{namespace}/users/{userid}/entitlements	ADMIN:NAMESPACE:{namespace}:USER:{userid}:ENTITLEMENT <READ>	When a request tries to access a resource via: GET /admin/namespaces/accelbyte/users/1234/entitlements, the actual required permission would be ADMIN:NAMESPACE:accelbyte:USER:1234:ENTITLEMENT <READ>

• OBJECTNAME: this required token represents the protected resource object, such as PROFILE or CURRENCY. For example, this is an admin permission for an endpoint that searches for currency in a namespace:

  Endpoint	Permission	Description
  GET /admin/namespace/{namespace}/currencies	ADMIN:NAMESPACE:{namespace}:CURRENCY <READ>	A permission resource can contain more than one object name delimited by colons, but we don't recommend doing this.

Permission Grant

In Shared Cloud

In Shared Cloud, granting permissions to user roles and IAM clients, can easily be done by toggling permissions as needed. For more details, Create an IAM client and Add and edit IAM client permissions.

In Private Cloud

In Private Cloud, permissions are manually granted to users and applications by providing permission resources. To do this, you must follow proper syntax of permissions as explained in the Syntax section.

note

The toggle permissions functionality, similar to Shared Cloud, will be available soon in Private Cloud.

Here's a template of a granted permission which includes four separate tokens:

[ADMIN:][NAMESPACE:<namespace>:][USER:<userId>:]<OBJECTNAME>

• ADMIN: This is the same as the permission requirement in the ADMIN endpoints. You should prefix it for the permissions of an administrative resource. For example, an admin permission for the roles CRUD (Create, Read, Update, Delete).

  Permission	Description
  ADMIN:ROLE <CREATE> | <READ> | <UPDATE> | <DELETE>	The logic between actions is a Bitwise OR (|).

• NAMESPACE:{namespace}: optional; use only if the resource is under namespace level.

  The syntax is NAMESPACE:, with a namespace name placeholder {namespace}, a *(wildcard), or a specific namespace name following.

  • {namespace}: This value tells the backend to dynamically resolve it to the granted namespace from the user or application. It means clients and users with corresponding permissions to that namespace can only use resources in a specific namespace. For example, this is a permission to grant access for creating IAM Clients in the namespace the system grants to user accounts and applications.

    Permission	Description
    ADMIN:NAMESPACE:{namespace}:CLIENT <CREATE>	The system interprets an asterisk ("*") as a wildcard, allowing access to that resource in all namespaces. For example, this is a permission to grant access for creating IAM Clients in any namespace: ADMIN:NAMESPACE:*:CLIENT

  • Specific namespace name: If you specify a namespace (e.g., NAMESPACE:namespace_A), the system grants permission only for resources in that specific namespace. A super admin can use this to provide a way to grant limited admin access to Customer Support users for resources in a specific game namespace only.

    Permission	Description
    ADMIN:NAMESPACE:namespace_A:CLIENT <CREATE>	This permission grants access for creating IAM Clients in a specific namespace (namespace_A) only.

• USER:userId: This is optional; you should only use it for user-specific resources.

  The syntax is USER: followed by either a user ID placeholder {userid}, or a wildcard asterisk.

  • {userid}: this value tells the backend to dynamically bind to the ID of a logged in user, replacing {userid} with the user's actual ID. This means that clients and users granted corresponding permissions can use the resources belonging to a specific user. For example, this is a permission to grant access to search for logged-in user entitlements in any namespace.

    Permission	Description
    ADMIN:NAMESPACE:*:USER:{userid}:ENTITLEMENT <READ>

    The system interprets an asterisk as a wildcard, allowing access to resources belonging to any user. For example, this is a permission to grant access for searching for entitlements from any user in any namespace: ADMIN:NAMESPACE:\*:USER:\*:ENTITLEMENT <READ>.

• OBJECTNAME: this is almost the same as the permission requirement in the ADMIN endpoints. The syntax here is either a specific object name or a wildcard asterisk.

  • Specific object name: represents the protected resource object. For example, this is a permission to grant access for searching for the profile belonging to a specific user in a specific namespace.

    Permission	Description
    ADMIN:NAMESPACE:{namespace}:USER:{userid}:PROFILE <READ>	If you want to grant access to all resource objects, replace the object name with a wildcard asterisk. For example, this is a permission to grant access to search for anything from the logged-in user in any namespace: ADMIN:NAMESPACE:*:USER:{userid}:* <READ>

Troubleshooting

This section lists errors and issues that may occur when using the service.

How to find the required permissions of each AGS endpoint?

Search for the API Endpoint documentation, which lists the permission required for each endpoint.

How to resolve errors related to Permissions?

Check the Errors and Exceptions in the Resources section.

What's next?

Learn how to manage user roles and manage IAM clients.