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

Master permissions

Last updated on March 12, 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.

    注記

    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:

    EndpointPermissionDescription
    GET /iam/v3/admin/rolesADMIN: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:

    EndpointPermissionDescription
    POST /iam/v3/admin/namespaces/{namespace}/clientsADMIN: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:

    EndpointPermissionDescription
    GET /admin/namespaces/{namespace}/users/{userid}/entitlementsADMIN: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:

    EndpointPermissionDescription
    GET /admin/namespace/{namespace}/currenciesADMIN: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 Starter, 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.

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.

Check the Errors and Exceptions in the Knowledge Base.

What's next?

Learn how to manage user roles and manage IAM clients.