# Permissions

Environment-level access control

Source: https://keyenv.dev/docs/api/permissions/

Environment-level access control

## Get my permissions

```http
GET /api/v1/projects/{projectId}/my-permissions
```

Returns the current user's permissions for all environments in a project

**Operation ID:** `getMyPermissions` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | User permissions | `MyPermissionsResponse` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `permissions` | `object[]` |  |
| `is_team_admin` | `boolean` |  |

### Example

```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/my-permissions" \
  -H "Authorization: Bearer $KEYENV_TOKEN"
```

## List environment permissions

```http
GET /api/v1/projects/{projectId}/environments/{environmentId}/permissions
```

Lists all user permissions for an environment

**Operation ID:** `listEnvironmentPermissions` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | List of permissions | `object[]` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` |  |
| `environment_id` | `string (uuid)` |  |
| `user_id` | `string (uuid)` |  |
| `user_email` | `string (email)` |  |
| `role` | `enum (none, read, write, admin)` |  |
| `granted_by` | `string (uuid)` |  |
| `created_at` | `string (date-time)` |  |
| `updated_at` | `string (date-time)` |  |

### Example

```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/permissions" \
  -H "Authorization: Bearer $KEYENV_TOKEN"
```

## Bulk set permissions

```http
PUT /api/v1/projects/{projectId}/environments/{environmentId}/permissions
```

Sets permissions for multiple users at once

**Operation ID:** `bulkSetPermissions` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |

### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `permissions` | `object[]` | yes |  |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Permissions updated |  |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |

### Example

```bash
curl -X PUT "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/permissions" \
  -H "Authorization: Bearer $KEYENV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"permissions":[{"user_id":"00000000-0000-0000-0000-000000000000","role":"none"}]}'
```

## Get user permission

```http
GET /api/v1/projects/{projectId}/environments/{environmentId}/permissions/{userId}
```

Returns a specific user's permission for an environment

**Operation ID:** `getUserPermission` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `userId` | `string (uuid)` | yes | User UUID |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | User permission | `EnvironmentPermission` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` |  |
| `environment_id` | `string (uuid)` |  |
| `user_id` | `string (uuid)` |  |
| `user_email` | `string (email)` |  |
| `role` | `enum (none, read, write, admin)` |  |
| `granted_by` | `string (uuid)` |  |
| `created_at` | `string (date-time)` |  |
| `updated_at` | `string (date-time)` |  |

### Example

```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/permissions/{userId}" \
  -H "Authorization: Bearer $KEYENV_TOKEN"
```

## Set user permission

```http
PUT /api/v1/projects/{projectId}/environments/{environmentId}/permissions/{userId}
```

Sets a user's permission for an environment

**Operation ID:** `setUserPermission` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `userId` | `string (uuid)` | yes | User UUID |

### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | `enum (none, read, write, admin)` | yes |  |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Permission set | `EnvironmentPermission` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` |  |
| `environment_id` | `string (uuid)` |  |
| `user_id` | `string (uuid)` |  |
| `user_email` | `string (email)` |  |
| `role` | `enum (none, read, write, admin)` |  |
| `granted_by` | `string (uuid)` |  |
| `created_at` | `string (date-time)` |  |
| `updated_at` | `string (date-time)` |  |

### Example

```bash
curl -X PUT "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/permissions/{userId}" \
  -H "Authorization: Bearer $KEYENV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role":"none"}'
```

## Delete user permission

```http
DELETE /api/v1/projects/{projectId}/environments/{environmentId}/permissions/{userId}
```

Removes a user's explicit permission for an environment

**Operation ID:** `deleteUserPermission` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |
| `environmentId` | `string` | yes | Environment UUID or name (e.g., "development", "staging", "production") |
| `userId` | `string (uuid)` | yes | User UUID |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `204` | Permission deleted |  |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |

### Example

```bash
curl -X DELETE "https://api.keyenv.dev/api/v1/projects/{projectId}/environments/{environmentId}/permissions/{userId}" \
  -H "Authorization: Bearer $KEYENV_TOKEN"
```

## Get default permissions

```http
GET /api/v1/projects/{projectId}/permissions/defaults
```

Returns default permissions for new team members in a project

**Operation ID:** `getDefaultPermissions` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Default permissions | `object[]` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` |  |
| `project_id` | `string (uuid)` |  |
| `environment_name` | `string` | Environment name or "*" for all |
| `default_role` | `enum (none, read, write, admin)` |  |
| `created_at` | `string (date-time)` |  |

### Example

```bash
curl -X GET "https://api.keyenv.dev/api/v1/projects/{projectId}/permissions/defaults" \
  -H "Authorization: Bearer $KEYENV_TOKEN"
```

## Set default permissions

```http
PUT /api/v1/projects/{projectId}/permissions/defaults
```

Sets default permissions for new team members

**Operation ID:** `setDefaultPermissions` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | yes | Project UUID or slug (e.g., "my-project") |

### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaults` | `object[]` | yes |  |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Defaults updated |  |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |

### Example

```bash
curl -X PUT "https://api.keyenv.dev/api/v1/projects/{projectId}/permissions/defaults" \
  -H "Authorization: Bearer $KEYENV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"defaults":[{"environment_name":"string","default_role":"none"}]}'
```