Skip to main content

Create a new Environment

Creating a new environment is as simple as clicking the New Environment button and filling in the details.

Creating Environment via API​

You can also create a new environment via the API.

curl 'https://api.permit.io/v2/projects/<project-id>/envs' \
  -H 'authorization: Bearer <api-key>' \
  --data-raw '{"key":"new-env-name","name":"New Env Name"}'
Remember

Make sure to use an Organization-level API Key or Project-level API Key to create a new Environment. Read more about API Key levels.

Default Role Creation​

When creating a new environment, you can choose whether to automatically create default roles and permissions. This feature helps you get started quickly by providing a standard set of roles (Admin, Editor, and Viewer) with predefined permissions for new resources.

Default role creation is disabled by default. You can enable it when creating a new environment through the API or in the policy-editor setting in the UI.

New Environment's Default Settings​

When creating a new environment, you can configure default resources and roles. The default settings include:

{
  "default_resource_actions": ["create", "read", "update", "delete"],
  "default_resource_permissions": {
    "admin": ["create", "read", "update", "delete"],
    "editor": ["create", "read", "update"],
    "viewer": ["read"]
  },
  "enable_default_roles": false
}
note

enable_default_roles defaults to false. This means default roles will not be automatically created unless you explicitly enable them.

Toggle Default Role Creation in the UI​

You can enable or disable default role creation using the toggle button in the policy editor settings. Visit the settings button in the policy editor section to access this toggle. This toggle allows you to control automatic creation of default roles and actions:

  • Enabled: When toggled on, the default roles (Admin, Editor, Viewer) with their predefined permissions will be automatically created for new resources in the environment.
  • Disabled: When toggled off (default), no default roles will be created automatically. You'll need to create roles manually as needed.

Enable Default Roles via API​

You can enable default role creation by setting enable_default_roles to true in the request body when creating a new environment:

curl 'https://api.permit.io/v2/projects/<project-id>/envs' \
  -H 'authorization: Bearer <api-key>' \
  --data-raw '{"key":"new-env-name","name":"New Env Name", "settings": {"enable_default_roles": true}}'

If you want to explicitly disable default roles (or keep them disabled), you can set enable_default_roles to false:

curl 'https://api.permit.io/v2/projects/<project-id>/envs' \
  -H 'authorization: Bearer <api-key>' \
  --data-raw '{"key":"new-env-name","name":"New Env Name", "settings": {"enable_default_roles": false}}'

Coping / Merging Environments​

Environments can be copied into new environments or existing environments. This is useful when you want to manage changes to the Policy, like adding a Resource, Role or Condition Set, in a controlled manner.

For example, if you want to test adding a new Resource to your policy, you can copy the environment, make the changes, and test them on the new environment, then merge it back.

In this example, we have a Production environment with a policy that has a File Resource and an Editor Role. We've copied the Production environment into a Development environment, where we've added a Folder Resource and an Admin Role. After testing the changes, we've merged the Development environment back into the Production environment.

This way, you can manage changes to your policy, such as code changes in your CI/CD pipelines. Read more about Policy Life Cycle with Permit.

Copy Environments via API​

You can copy an environment into a new environment or an existing environment via the API.

curl --location 'https://api.permit.io/v2/projects/{project_id}/envs/{env_id}/copy' \
  -H 'authorization: Bearer API_SECRET_KEY' \
  --data '{
  "target_env": {
    "new": {
        "key": "prod",
        "name": "production"
    }
  }'

Read more about copying environments in the API Documentation.

Copy Environment - Background API​

For large environments, copying environments can take some time. You can use the Background API to copy environments asynchronously.

curl --location 'https://api.permit.io/v2/projects/default/envs/staging/copy/async' \
  -H 'authorization: Bearer API_SECRET_KEY' \
  --data '{
  "target_env": {
    "new": {
        "key": "prod",
        "name": "production"
    }
  }'

For more information, read the Background API Documentation.

Supported Objects​

Copy and merge environments apply only to Policy objects, such as Resources, Roles, and Condition Sets. Directory objects, such as Users, Tenants, and Resource Instances, are not copied or merged.

When copying environments, the marked objects below are copied:

  • Resource
    • Resource Actions
    • Resource Action Groups
    • Resource Attributes
    • Resource Roles
    • Resource Relations
  • Roles
    • Role Permissions
    • Role Derivations
    • Role Hierarchy
  • Condition Sets
    • User Sets
    • Resource Sets
    • Condition Sets Rules
    • Condition Sets Inheritance
  • Custom Policies *

Custom Policies​

When using GitOps with a Custom Git Repository, all files under the Environment's branch are copied into the new Environment's branch, including all Custom .rego Policy files.

Conflict Strategy​

When merging into an existing environment, conflicts can arise if the same resource or role is modified in both environments.

In this example, we've added an Admin Role to the Production environment after copying it into the Development environment. When we merge the development environment back into the production environment, we will have a conflict with the Admin role.

When merging environments, you can choose to resolve conflicts by either:

  • Fail: (default) Fail the merge, rollback the entire merge operation and keep the existing object in the target environment.
  • Overwrite: Overwrite the existing object on the target environment with the object from the source environment.

Excluding / Including Objects​

When copying environments, you can choose to set a scope to exclude or include specific objects from the copy operation.

curl --location 'https://api.permit.io/v2/projects/{project_id}/envs/{env_id}/copy' \
  -H 'authorization: Bearer API_SECRET_KEY'\
  --data '{
  "target_env": {
    "new": {
        "key": "prod",
        "name": "production"
    }
  },
  "scope": {
      "roles": {
          "exclude": ["*"]
      },
      "resources": {
          "include": ["folder", "file"]
      },
      "resource_sets": {
          "exclude": ["test*"]
      },
      "user_sets": {
          "exclude": ["canada_users"]
      },
      "custom_policies": {
          "include": ["*.rego"]
      }
  }
}'

Using wildcards is supported for exclude and include scopes to match multiple objects. The wildcard uses the Unix filename pattern matching.

Customize GitOps Branch Name​

When creating or copying environments, you can customize the branch name for the new environment. Notice that the Policy Repo should be activated on the project for it to work properly.

curl 'https://api.permit.io/v2/projects/{project_id}/envs' \
  -H 'authorization: Bearer {API_SECRET_KEY}'\
  --data-raw '{"key":"new-env-name","name":"New Env Name", "custom_branch_name": "new-env-branch-name"}'

Now, in your custom Git Repository, you will see a new branch named new-env-branch-name that corresponds to the new environment.

You can also specify a custom branch name when copying a new environment or update existing environments to a new branch name.

curl 'https://api.permit.io/v2/projects/{project_id}/envs/{env_id}' -X 'PATCH' \
  -H 'authorization: Bearer {API_SECRET_KEY}'\
  --data-raw '{"custom_branch_name": "new-env-branch-name"}'

Read more about GitOps and Permit.

Contents