Create a new role

Last updated on September 29, 2026

Overview

This article contains information on how to create a new role in your environment using the AccelByte Gaming Services (AGS) Admin Portal or the AGS CLI.

AGS Public Cloud

The ability to customize your own roles in Public Cloud will be available soon.

Prerequisites

• You have access to the Admin Portal and have sufficient permissions for roles management.

• In Private Cloud, make sure you have the following permissions:

  Usage	Resource	Action
  Create Role	ADMIN:ROLE	Create
  Add Role Permissions	ADMIN:ROLE	Update
  Invite User Admin	ADMIN:NAMESPACE:{namespace}:USER:INVITE	Create
  Admin Add User's Role	ADMIN:NAMESPACE:{namespace}:ROLE:USER:*	Update

• To follow the AGS CLI steps, you have installed the AGS CLI and signed in with an account that meets the requirements above. See Install and sign in. The examples use a Bash shell.

Create a new role

Follow the steps below to create a new role:

Admin Portal

1. On the Admin Portal sidebar, go to Admin Task > Roles & Permissions.

   

2. On the Roles page, click Create role.

   

3. Choose whether to clone an existing role or to create a new role from scratch.

   info

   The system default prompts you to clone an existing role. This enables you to quickly create new roles that carry over all the permissions from the cloned role.

   • To clone an existing role, fill in the Create New Role fields with the following information:

     • Type in a name for the role in the Role Name field.

     • Select the existing role that you want to clone from the Select Role dropdown.

       

   • To create a new role without cloning, select the I want to create a new role from scratch checkbox and fill in the fields with the following information:

     • Type in a name for the role in the Role Name field.

     • Select the Set as Admin Role checkbox if you want your role to have access to the Admin Portal.

     • Select the Set as Global Role checkbox if you want your role to be able to access all namespaces.

       

4. Click Create.

AGS CLI

1. Choose whether to clone an existing role or to create a new role from scratch. To clone a role, find the role that you want to clone. For each role, the output shows its roleId and its name (roleName). To create a role from scratch, skip to step 3.

   ags iam roles list --page-all --format json

2. Save the role that you want to clone to a file. Replace <SourceRoleId> with its roleId. Any file name works. This example uses source-role.json:

   ags iam roles get --role-id <SourceRoleId> --format json > source-role.json

   Note the role's adminRole and isWildcard values, which you use in the next step. Then delete every field except permissions. Don't change the permissions list, because these are the permissions that the new role gets in step 4. The file then looks like this, with one entry for each of the cloned role's permissions:

   {
     "permissions": [
       { "resource": "ADMIN:NAMESPACE:{namespace}:USER", "action": 2 },
       { "resource": "ADMIN:NAMESPACE:{namespace}:ROLE:USER:*", "action": 4 }
     ]
   }

   warning

   Remove roleId from the file. If the file still contains it, the command in step 4 adds the permissions to the role that you cloned instead of the new role.

3. Create the role. Replace <RoleName> with a name for the role, from 1 to 48 characters long:

   ags iam roles create --json '{"roleName": "<RoleName>", "adminRole": false, "isWildcard": false}'

   • adminRole: the Set as Admin Role checkbox. Set it to true to give the role access to the Admin Portal.
   • isWildcard: the Set as Global Role checkbox. Set it to true to let the role access all namespaces.

   When you clone a role, use the values that you noted in step 2, the same as the Admin Portal does. The output shows the new role's roleId.

4. Add permissions to the new role. Replace <NewRoleId> with the roleId from step 3.

   • If you cloned a role, add the permissions from the file that you edited in step 2. If the permissions list is empty, skip this step.

     ags iam roles add-permissions --role-id <NewRoleId> --json @source-role.json

   • If you created an admin role from scratch, add the Read permissions that the Admin Portal adds to every admin role it creates. Create a JSON file with this content. Any file name works. This example uses admin-permissions.json:

     {
       "permissions": [
         { "resource": "ADMIN:ROLE", "action": 2 },
         { "resource": "ADMIN:NAMESPACE", "action": 2 },
         { "resource": "ADMIN:NAMESPACE:{namespace}:NAMESPACE", "action": 2 },
         { "resource": "ADMIN:NAMESPACE:{namespace}:CONFIG:COMMON", "action": 2 }
       ]
     }

     Then add the permissions:

     ags iam roles add-permissions --role-id <NewRoleId> --json @admin-permissions.json

   • If you created a role from scratch that isn't an admin role, skip this step.

You've successfully created a new role in your environment. You can now add permissions to it or assign in to a user.

What's next

• Add permissions to a role