Skip to main content
Version: 2.0.0

Manage Environments

A Permit environment is a silo (a logical grouping) of your policy (roles, conditions, etc.) and data (users, tenants, role assignments, etc.). You can create multiple environments for each of your projects. For example, you can create a production environment for your production deployment and a staging environment for your staging deployment. Environments can be used for CI/D flows, testing, and more.

Create new environment​

Remember

Make sure you use an organization level api-key or project level api-key to create a new environment.

First of all we need to get our API_SECRET_KEY from the dashboard and get current project_id

Replace API_SECRET_KEY with your API_SECRET_KEY and project_id with your project_id in the following command.

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"}'

The return environment object will look like this:

{
  "key": "new-env-key",
  "id": "f77b6ee3149e4b90ba3263ecd092xxxx",
  "organization_id": "903ebc2765b848289d6dfbd3c21exxxx",
  "project_id": "3c4244c7bcab4c97990e5bc724dafe85",
  "created_at": "2023-07-30T15:56:21+00:00",
  "updated_at": "2023-07-30T15:56:21+00:00",
  "name": "New Env Name",
  "description": null,
  "custom_branch_name": null,
  "jwks": null,
  "settings": null
}

Copy Environment​

The copy environment endpoint allows you to copy an existing environment to a new environment or an existing environment.
It allows you to copy the entire environment or a subset of the policy in a specific environment.
You can also exclude or include specific objects from the copy, it also supports * so you can exclude all the roles that starts with test*

You can either duplicates an existing environment to a new environment in the same project, or copies from an existing environment to another existing environment.

Copying environments across projects or organizations is not allowed.

Remember

Make sure you use an organization level api-key or project level api-key to copy an environment.

Copy to a new environment​

In this example I'm coping production environment to a new environment called production.
And I'm excluding all the roles, resources, user_sets and resource_sets that starts with test*.

Example​

First of all we need to get our API_SECRET_KEY from the dashboard and get current project_id and env_id

Replace API_SECRET_KEY with your API_SECRET_KEY and project_id with your project_id and env_id with your env_id in the following command.

#curl --location 'https://api.permit.io/v2/projects/default/envs/staging/copy' \
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": ["test*"]
      },
      "resources": {
          "exclude": ["test*"]
      },
      "resource_sets": {
          "exclude": ["test*"]
      },
      "user_sets": {
          "exclude": ["test*"]
      }
  }
}'

You should get 201 response with the new environment object

Copy to an existing environment​

In this example I'm coping production environment to an existing environment called staging.
And I'm overwriting any existing objects in the target environment. (conflict_strategy: overwrite)
I can also use the fail strategy to fail the copy if there is any conflict in the target environment.

Example​

First of all we need to get our API_SECRET_KEY from the dashboard and get current project_id and env_id

Replace API_SECRET_KEY with your API_SECRET_KEY and project_id with your project_id and env_id with your env_id in the following command.

#curl --location 'https://api.permit.io/v2/projects/{project_id}/envs/{env_id}/copy' \
curl --location 'https://api.permit.io/v2/projects/default/envs/production/copy' \
  -H 'authorization: Bearer API_SECRET_KEY'\
  --data '{
  "target_env": {
    "existing": "staging"
  },
  "conflict_strategy": "overwrite",
}'

You should get 201 response with the new environment object

Contents