Master permissions

Last updated on September 19, 2023

note

Permissions are in development for AGS Starter.

Overview

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.

Goals

The purpose of this documentation is to provide:

• An understanding of permissions and their use.
• Links to related guides that demonstrate permissions you can assign via IAM Clients, and Roles you can assign to your User Accounts.

Prerequisites

Familiarity with RESTful API design.

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:

  1. Trusted internal API calls between AGS and your applications, which IAM Clients authorizes.

  2. 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 permisisons. 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	DMIN:NAMESPACE:{namespace}:USER:{userId}:ENTITLEMENT <READ>	When a request tries to access a resource via: GET <code>/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

When granting permissions to your users or applications, follow the general syntax above.

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

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

In this section, you can find common errors and issues that may occur when using the service, along with recommendations on how to resolve them.

How to find the required permissions of each AGS endpoint

Search 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 Knowledge Base.

Next Steps

To continue learning about how to grant Permissions to user accounts and applications, please refer to our other guides.