Identity and Access Management

Getting Started

The Scalr IAM model was built with flexibility in mind to fit any type of organization. There are a few key components to think about when building IAM in Scalr:

  • Roles - A collection of permissions that can be assigned to a user or team.
  • Teams and Users - Teams and users must be assigned a role to be able to do anything in Scalr.
  • Access Policies - The component that links a role to a team/user.
  • Scope - Access policies can be assigned at the account, environment, or workspace scope.


Roles are collections of permissions. You will find that you can use two types of roles:

  • System roles - A set of permissions that have been pre-created for common use cases.
  • Custom roles - Roles that can be created by someone in the account that has permission to do so.

When creating a role, keep in mind where the object permissions need to be set. For example, the variable object exists at the account, environment, and workspace scope. When building a role, you only see the variable:* permission as the scope of the permission is set with access policies.


Users and Teams

An individual user or team can be granted access to Scalr. Users and Teams can be managed locally in Scalr or by using an external identity provider, which is free on all plans in Scalr. See more on the SSO integration here.

A user or team must have an access policy assigned to it for them to be able to do anything in Scalr. Just inviting a user does not provide enough access to log into a Scalr account.


Access Policies

Access policies are the combination of a user, team, or service account and a role. When linked, access policies are what give users the ability to do anything in Scalr. The policies can be set at three scopes:

  • Account - Account policies grant access to the account in general and to any object within the account scope.
  • Environment - Environment access policies can grant permissions to the specific environment.
  • Workspace - Workspace access policies can grant permissions to the specific environment.

Access policies in conjunction with the Scalr scope are what make Scalr extremely flexible. For example, let's say your Scalr environments have a one-to-one mapping with application teams. Every time an application is onboarded into Scalr, an environment is created, and an initial workspace containing the core infrastructure for the application is deployed. In this case, there is the ability to give full admin access to the core infrastructure workspace to the central IT team. Then the app team will have read-only to that workspace to be able to get output information or be able to do remote state data lookups as needed. The app team then has full admin access to all other objects within the environment and all new workspaces.

Another example is module management. Modules can be managed at the account of environment scope. It is common for a platform team to manage all shared modules at the account scope, which can be used by all environments and teams. In this case, the platform team will have an access policy that only gives them access to the module registry at the account scope and no access to an environment. The app teams will then have the ability to use the modules within their environment and can have an access policy assigned to them to allow them to create app-specific modules only in their environment. This will give a cumulative approach of modules from the account and environment scope without having to worry about users deleting any shared modules.


Here are a couple of examples of how to use roles and access policies:

ScenarioHow To
A team requires full access to a specific environment.Create an environment access policy with the system user role.
A team only needs to manage modules at the account scope.Create a custom role with accounts:read and modules:*

Assign the above role to a team using an access policy at the account scope.
A team requires access to one workspace to read plan outputs and state files.Assign the system role environment-min-access to the team as an environment access policy.

Create a custom role with permissions plans:read-json-output, state-versions:read, workspaces:read.

Assign the above role to a team using an access policy at the workspace scope.
A team requires read-only access to all environments in the account.Create an account access policy with the system role environment-min-accessas an account access policy

Service Accounts

A service account in Scalr is a local user that can be created, even if LDAP or SAML is enabled, to allow external services to call Scalr without the API token being linked to a named account. It is best practice to avoid using an employee or user API token to integrate with Scalr in the event the employee or user leaves the company. The service account will always remain active unless updated by an administrator. The permissions for a service account are granted the same way permissions are granted for users and teams through access policies.



Team ownership can be assigned to service accounts to allow teams to independently create and manage their own service accounts and assign them to environments.

The following Terraform resource allows you to configure the IAM role needed to manage service accounts and assign owners.

resource "scalr_role" "owner" {
  name = "service-account-owners"
  description = "Allows user to manage service accounts and assign ownership"
  permissions = [

The role must be granted to a team at the account scope.

WARNING If a service account is created without team ownership then anyone with the above permissions will be able to update, read, or delete it.

Admin users can be granted the ownership:bypass permission at the account level to bypass team ownership if they are not part of the team that owns the service account, but need to manage it.