Custom roles

This page describes how to create, modify and delete custom roles in STACKIT using either the Portal or API.

Understanding custom roles

Roles are containers for permissions. They allow permissions to be bundled together and reused. Roles can be assigned to users, groups or service accounts. The permissions bundled in a role allow the assignee to perform specific actions on various STACKIT resources. Permissions cannot be granted individually, but must be assigned to a role.

STACKIT provides a number of pre-defined roles for its resources, such as owner, editor, and reader. You can also define roles with custom sets of permissions, known as custom roles. Distributing permissions to your users, groups and service accounts this way can make it easier to practice the principle of least privilege, which states that users should only have exactly those permissions they need, and no more.

Creating a custom role

Before attempting to create a custom role, ensure you have the iam.role.add permission assigned. Custom roles can be created either in the STACKIT Portal or using the API:

Portal

Make sure you have selected the resource you would like to create a custom role for, using the resource manager. Then, in the sidebar of the portal, navigate to IAM and Management > Roles. Click on the ’+ Create Role’ button to open the dialog.

The role name must only consist of lowercase letters that optionally can be separated by single dots or single hyphens.

Add a description and select the permissions that you would like to add to your new custom role. Finally, when you are finished click the ‘create’ button to create your new custom role. Your custom role should now be created. If you wish to add subjects to your custom role, locate your new custom role in the ‘General Roles’ overview, click on the ’⋮’ button for the custom role you wish to grant access to and click on ‘Grant Access’. From here you can grant access to custom roles the same way you would any other role. Click ‘save’ to complete the process.

API

Use the following API call to create a new custom role for your resource.

The role name must only consist of lowercase letters that optionally can be separated by single dots or single hyphens.

PATCH https://authorization.api.stackit.cloud/v2/{resourceId}/roles
Content-Type: application/json

{
  "resourceType": "project",
  "roles": [
    {
      "description": "Custom role for the development team.",
      "name": "dev-team-custom-role",
      "permissions": ["logs.instance.get", "logs.instance.list", "postgres-flex.database.get"]
    }
  ]
}

Modifying a custom role

Existing custom roles can be modified (e.g. changing the name, adding permissions).

Portal

To do so via the portal, navigate to IAM and Management > Roles and select the custom role from the role overview. A menu will appear, which allows you to modify the custom role name, description and its permissions. Click ‘save’ once you are done with your changes. Should you want to grant or revoke access to the custom role, navigate to IAM and Management > Access.

API

Use the following API call to modify an existing custom role:

PUT https://authorization.api.stackit.cloud/v2/{resourceType}/{resourceId}/roles/{roleId}
Content-Type: application/json

{
  "description": "Custom role for the development team.",
  "name": "dev-team-custom-role",
  "permissions": [
    {
      "name": "iam.member.read"
    }
  ]
}

Deleting a custom role

Should you no longer need a custom role, you may delete it via the STACKIT Portal or API.

Portal

Make sure that you have selected the resource you would like to create a custom role for, using the resource manager. Then, in the sidebar of the portal, navigate to IAM and Management > Roles. Select the custom role you want to delete from the overview and click the ’⋮’ button to show the options for this custom role. To delete the custom role, simply click ‘delete’ and confirm your choice.

API

Use the following API call to delete a custom role:

DELETE https://authorization.api.stackit.cloud/v2/{resourceType}/{resourceId}/roles/{roleId}