Environment Protection API

Environment protections prevent unauthorized users from running commands against sensitive environments (e.g., prod). When a protection is active for an environment, only users on the exception list can target that environment.

The dagctl CLI calls the GET /api/v1/environment-protections/check endpoint before executing any command that targets a protected environment.

GET /api/v1/environment-protections

Returns all environment protections for your organization. Requires the manage_secrets permission.

Response

{
  "protections": [
    {
      "id": "ep_abc123",
      "organization_id": "org-xxxxxxxx",
      "environment_name": "prod",
      "enabled": true,
      "created_by": "user_abc123",
      "created_at": "2026-01-20T09:00:00Z",
      "updated_at": "2026-01-20T09:00:00Z"
    }
  ],
  "total": 1
}

GET /api/v1/environment-protections/:id

Returns a single environment protection, including its exception user list.

Path Parameters

Parameter	Type	Description
`id`	string	Protection ID

Response

{
  "id": "ep_abc123",
  "organization_id": "org-xxxxxxxx",
  "environment_name": "prod",
  "enabled": true,
  "excepted_users": [
    {
      "user_id": "user_def456",
      "email": "alice@acme.com"
    }
  ],
  "created_by": "user_abc123",
  "created_at": "2026-01-20T09:00:00Z",
  "updated_at": "2026-03-15T11:00:00Z"
}

POST /api/v1/environment-protections

Creates a new environment protection. Requires the manage_secrets permission.

Request Body

{
  "environment_name": "prod",
  "enabled": true
}

Field	Type	Required	Description
`environment_name`	string	yes	Environment name to protect (must match your SQLMesh environment)
`enabled`	boolean	no	Whether the protection is active (default: `true`)

Response

Returns 201 Created with the created protection object.

PUT /api/v1/environment-protections/:id

Updates an environment protection. You can rename the environment or toggle the protection on/off.

Path Parameters

Parameter	Type	Description
`id`	string	Protection ID

Request Body

{
  "enabled": false
}

Field	Type	Description
`environment_name`	string	Rename the protected environment
`enabled`	boolean	Enable or disable the protection

Response

Returns 200 OK with the updated protection object.

DELETE /api/v1/environment-protections/:id

Deletes an environment protection.

Path Parameters

Parameter	Type	Description
`id`	string	Protection ID

Response

{
  "message": "Environment protection deleted successfully"
}

POST /api/v1/environment-protections/:id/users

Adds a user to the exception list for a protection. Users on the exception list can run commands against the protected environment even when the protection is enabled.

Path Parameters

Parameter	Type	Description
`id`	string	Protection ID

Request Body

{
  "user_id": "user_def456"
}

Field	Type	Required	Description
`user_id`	string	yes	ID of the user to add to the exception list. The user must belong to your organization.

Response

{
  "message": "User added to environment protection successfully"
}

DELETE /api/v1/environment-protections/:id/users/:userId

Removes a user from the exception list.

Path Parameters

Parameter	Type	Description
`id`	string	Protection ID
`userId`	string	User ID to remove from the exception list

Response

{
  "message": "User removed from environment protection successfully"
}

GET /api/v1/environment-protections/check

Checks whether the authenticated user has access to a given environment. Returns 403 if a protection is active and the user is not on the exception list.

This endpoint is called by the dagctl CLI before running any command. You can also call it programmatically to gate access in your own tooling.

Query Parameters

Parameter	Type	Description
`project_id`	string	Project ID. If provided and `environment` is omitted, the project's configured environment is used.
`environment`	string	Environment name to check access for.

At least one of project_id or environment is required.

Response (access granted)

{
  "allowed": true,
  "environment": "prod",
  "message": "Access granted"
}

Response (access denied)

HTTP 403:

{
  "allowed": false,
  "environment": "prod",
  "message": "Environment 'prod' is protected. You do not have permission to run commands against this environment. Contact your organization admin for access."
}