# IAM API reference

Source: `@socra/iam-api@0.2.1` (IamContract).

Project IAM policies, identities, and credentials.

## API surface

Base URL: `https://iam.socra.cloud`

## Service authorization definitions

A producer-owned catalog of project permissions and predefined roles.

### Resource schema

- `service` string (min length: 1; max length: 253; pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$), required
- `permission_prefix` string (pattern: ^[a-z][a-z0-9]*$), required
- `role_prefix` string (pattern: ^[a-z][a-zA-Z0-9._-]*$), required
- `permissions` object[], required
  - `name` string (min length: 3; max length: 256; pattern: ^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$), required
  - `title` string (min length: 1; max length: 256), required
  - `description` string | null (default: null), required
  - `basic_roles` "owner" | "editor" | "viewer"[] (default: []), required
- `roles` object[], required
  - `name` string (min length: 7; max length: 256; pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$), required
  - `title` string (min length: 1; max length: 256), required
  - `description` string | null (default: null), required
  - `permissions` string[] (min items: 1), required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "service": {
      "type": "string",
      "minLength": 1,
      "maxLength": 253,
      "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"
    },
    "permission_prefix": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9]*$"
    },
    "role_prefix": {
      "type": "string",
      "pattern": "^[a-z][a-zA-Z0-9._-]*$"
    },
    "permissions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 3,
            "maxLength": 256,
            "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "description": {
            "default": null,
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2000
              },
              {
                "type": "null"
              }
            ]
          },
          "basic_roles": {
            "default": [],
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "owner",
                "editor",
                "viewer"
              ]
            }
          }
        },
        "required": [
          "name",
          "title",
          "description",
          "basic_roles"
        ],
        "additionalProperties": false
      }
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 7,
            "maxLength": 256,
            "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "description": {
            "default": null,
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2000
              },
              {
                "type": "null"
              }
            ]
          },
          "permissions": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 3,
              "maxLength": 256,
              "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
            }
          }
        },
        "required": [
          "name",
          "title",
          "description",
          "permissions"
        ],
        "additionalProperties": false
      }
    },
    "updated_at": {}
  },
  "required": [
    "service",
    "permission_prefix",
    "role_prefix",
    "permissions",
    "roles",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Get service authorization definition

`GET /admin/v1/service-authorizations/{service}`

#### Path parameters

- `service` string (min length: 1; max length: 253; pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$), required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "string",
  "minLength": 1,
  "maxLength": 253,
  "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"
}
```


#### Response

- `service` string (min length: 1; max length: 253; pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$), required
- `permission_prefix` string (pattern: ^[a-z][a-z0-9]*$), required
- `role_prefix` string (pattern: ^[a-z][a-zA-Z0-9._-]*$), required
- `permissions` object[], required
  - `name` string (min length: 3; max length: 256; pattern: ^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$), required
  - `title` string (min length: 1; max length: 256), required
  - `description` string | null (default: null), required
  - `basic_roles` "owner" | "editor" | "viewer"[] (default: []), required
- `roles` object[], required
  - `name` string (min length: 7; max length: 256; pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$), required
  - `title` string (min length: 1; max length: 256), required
  - `description` string | null (default: null), required
  - `permissions` string[] (min items: 1), required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "service": {
      "type": "string",
      "minLength": 1,
      "maxLength": 253,
      "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"
    },
    "permission_prefix": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9]*$"
    },
    "role_prefix": {
      "type": "string",
      "pattern": "^[a-z][a-zA-Z0-9._-]*$"
    },
    "permissions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 3,
            "maxLength": 256,
            "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "description": {
            "default": null,
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2000
              },
              {
                "type": "null"
              }
            ]
          },
          "basic_roles": {
            "default": [],
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "owner",
                "editor",
                "viewer"
              ]
            }
          }
        },
        "required": [
          "name",
          "title",
          "description",
          "basic_roles"
        ],
        "additionalProperties": false
      }
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 7,
            "maxLength": 256,
            "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "description": {
            "default": null,
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2000
              },
              {
                "type": "null"
              }
            ]
          },
          "permissions": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 3,
              "maxLength": 256,
              "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
            }
          }
        },
        "required": [
          "name",
          "title",
          "description",
          "permissions"
        ],
        "additionalProperties": false
      }
    },
    "updated_at": {}
  },
  "required": [
    "service",
    "permission_prefix",
    "role_prefix",
    "permissions",
    "roles",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Synchronize service authorization definition

`PATCH /admin/v1/service-authorizations/{service}`

#### Path parameters

- `service` string (min length: 1; max length: 253; pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$), required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "string",
  "minLength": 1,
  "maxLength": 253,
  "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"
}
```


#### Request body

- `permission_prefix` string (pattern: ^[a-z][a-z0-9]*$), required
- `role_prefix` string (pattern: ^[a-z][a-zA-Z0-9._-]*$), required
- `permissions` object[], required
  - `name` string (min length: 3; max length: 256; pattern: ^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$), required
  - `title` string (min length: 1; max length: 256), required
  - `description` string | null (default: null), optional
  - `basic_roles` "owner" | "editor" | "viewer"[] (default: []), optional
- `roles` object[], required
  - `name` string (min length: 7; max length: 256; pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$), required
  - `title` string (min length: 1; max length: 256), required
  - `description` string | null (default: null), optional
  - `permissions` string[] (min items: 1), required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "permission_prefix": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9]*$"
    },
    "role_prefix": {
      "type": "string",
      "pattern": "^[a-z][a-zA-Z0-9._-]*$"
    },
    "permissions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 3,
            "maxLength": 256,
            "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "description": {
            "default": null,
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2000
              },
              {
                "type": "null"
              }
            ]
          },
          "basic_roles": {
            "default": [],
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "owner",
                "editor",
                "viewer"
              ]
            }
          }
        },
        "required": [
          "name",
          "title"
        ]
      }
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 7,
            "maxLength": 256,
            "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "description": {
            "default": null,
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2000
              },
              {
                "type": "null"
              }
            ]
          },
          "permissions": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 3,
              "maxLength": 256,
              "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
            }
          }
        },
        "required": [
          "name",
          "title",
          "permissions"
        ]
      }
    }
  },
  "required": [
    "permission_prefix",
    "role_prefix",
    "permissions",
    "roles"
  ]
}
```

#### Response

- `service` string (min length: 1; max length: 253; pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$), required
- `permission_prefix` string (pattern: ^[a-z][a-z0-9]*$), required
- `role_prefix` string (pattern: ^[a-z][a-zA-Z0-9._-]*$), required
- `permissions` object[], required
  - `name` string (min length: 3; max length: 256; pattern: ^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$), required
  - `title` string (min length: 1; max length: 256), required
  - `description` string | null (default: null), required
  - `basic_roles` "owner" | "editor" | "viewer"[] (default: []), required
- `roles` object[], required
  - `name` string (min length: 7; max length: 256; pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$), required
  - `title` string (min length: 1; max length: 256), required
  - `description` string | null (default: null), required
  - `permissions` string[] (min items: 1), required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "service": {
      "type": "string",
      "minLength": 1,
      "maxLength": 253,
      "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"
    },
    "permission_prefix": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9]*$"
    },
    "role_prefix": {
      "type": "string",
      "pattern": "^[a-z][a-zA-Z0-9._-]*$"
    },
    "permissions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 3,
            "maxLength": 256,
            "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "description": {
            "default": null,
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2000
              },
              {
                "type": "null"
              }
            ]
          },
          "basic_roles": {
            "default": [],
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "owner",
                "editor",
                "viewer"
              ]
            }
          }
        },
        "required": [
          "name",
          "title",
          "description",
          "basic_roles"
        ],
        "additionalProperties": false
      }
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 7,
            "maxLength": 256,
            "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "description": {
            "default": null,
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2000
              },
              {
                "type": "null"
              }
            ]
          },
          "permissions": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 3,
              "maxLength": 256,
              "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
            }
          }
        },
        "required": [
          "name",
          "title",
          "description",
          "permissions"
        ],
        "additionalProperties": false
      }
    },
    "updated_at": {}
  },
  "required": [
    "service",
    "permission_prefix",
    "role_prefix",
    "permissions",
    "roles",
    "updated_at"
  ],
  "additionalProperties": false
}
```

## IAM permissions

Discoverable project permissions declared by Socra services.

### Resource schema

- `name` string (min length: 3; max length: 256; pattern: ^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$), required
- `title` string (min length: 1; max length: 256), required
- `description` string | null (default: null), required
- `basic_roles` "owner" | "editor" | "viewer"[] (default: []), required
- `service` string (min length: 1; max length: 253; pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$), required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 3,
      "maxLength": 256,
      "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    },
    "description": {
      "default": null,
      "anyOf": [
        {
          "type": "string",
          "maxLength": 2000
        },
        {
          "type": "null"
        }
      ]
    },
    "basic_roles": {
      "default": [],
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "owner",
          "editor",
          "viewer"
        ]
      }
    },
    "service": {
      "type": "string",
      "minLength": 1,
      "maxLength": 253,
      "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"
    }
  },
  "required": [
    "name",
    "title",
    "description",
    "basic_roles",
    "service"
  ],
  "additionalProperties": false
}
```

### List IAM permissions

`GET /v1/permissions`

#### Query parameters

- `service` string (min length: 1; max length: 253; pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$), optional

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "service": {
      "type": "string",
      "minLength": 1,
      "maxLength": 253,
      "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"
    }
  }
}
```

#### Response

- `data` object[], required
  - `name` string (min length: 3; max length: 256; pattern: ^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$), required
  - `title` string (min length: 1; max length: 256), required
  - `description` string | null (default: null), required
  - `basic_roles` "owner" | "editor" | "viewer"[] (default: []), required
  - `service` string (min length: 1; max length: 253; pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$), required
- `has_more` false, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 3,
            "maxLength": 256,
            "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "description": {
            "default": null,
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2000
              },
              {
                "type": "null"
              }
            ]
          },
          "basic_roles": {
            "default": [],
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "owner",
                "editor",
                "viewer"
              ]
            }
          },
          "service": {
            "type": "string",
            "minLength": 1,
            "maxLength": 253,
            "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"
          }
        },
        "required": [
          "name",
          "title",
          "description",
          "basic_roles",
          "service"
        ],
        "additionalProperties": false
      }
    },
    "has_more": {
      "type": "boolean",
      "const": false
    }
  },
  "required": [
    "data",
    "has_more"
  ],
  "additionalProperties": false
}
```

## IAM predefined roles

Discoverable predefined roles assignable in project IAM policies.

### Resource schema

- `name` string (min length: 7; max length: 256; pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$), required
- `title` string (min length: 1; max length: 256), required
- `description` string | null (default: null), required
- `permissions` string[] (min items: 1), required
- `service` string (min length: 1; max length: 253; pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$), required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 7,
      "maxLength": 256,
      "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    },
    "description": {
      "default": null,
      "anyOf": [
        {
          "type": "string",
          "maxLength": 2000
        },
        {
          "type": "null"
        }
      ]
    },
    "permissions": {
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 3,
        "maxLength": 256,
        "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
      }
    },
    "service": {
      "type": "string",
      "minLength": 1,
      "maxLength": 253,
      "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"
    }
  },
  "required": [
    "name",
    "title",
    "description",
    "permissions",
    "service"
  ],
  "additionalProperties": false
}
```

### List IAM predefined roles

`GET /v1/roles`

#### Query parameters

- `service` string (min length: 1; max length: 253; pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$), optional

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "service": {
      "type": "string",
      "minLength": 1,
      "maxLength": 253,
      "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"
    }
  }
}
```

#### Response

- `data` object[], required
  - `name` string (min length: 7; max length: 256; pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$), required
  - `title` string (min length: 1; max length: 256), required
  - `description` string | null (default: null), required
  - `permissions` string[] (min items: 1), required
  - `service` string (min length: 1; max length: 253; pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$), required
- `has_more` false, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 7,
            "maxLength": 256,
            "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "description": {
            "default": null,
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2000
              },
              {
                "type": "null"
              }
            ]
          },
          "permissions": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 3,
              "maxLength": 256,
              "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
            }
          },
          "service": {
            "type": "string",
            "minLength": 1,
            "maxLength": 253,
            "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"
          }
        },
        "required": [
          "name",
          "title",
          "description",
          "permissions",
          "service"
        ],
        "additionalProperties": false
      }
    },
    "has_more": {
      "type": "boolean",
      "const": false
    }
  },
  "required": [
    "data",
    "has_more"
  ],
  "additionalProperties": false
}
```

## IAM custom roles

A project-owned role composed from service-declared permissions.

### Resource schema

- `name` string (min length: 7; max length: 256; pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$), required
- `project_id` custom, required
- `role_id` string (min length: 3; max length: 64; pattern: ^[a-z][a-zA-Z0-9._-]*$), required
- `title` string (min length: 1; max length: 100), required
- `description` string | null, required
- `permissions` string[] (min items: 1; max items: 100), required
- `stage` "alpha" | "beta" | "ga" | "disabled", required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 7,
      "maxLength": 256,
      "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
    },
    "project_id": {},
    "role_id": {
      "type": "string",
      "minLength": 3,
      "maxLength": 64,
      "pattern": "^[a-z][a-zA-Z0-9._-]*$"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "description": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 500
        },
        {
          "type": "null"
        }
      ]
    },
    "permissions": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 3,
        "maxLength": 256,
        "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
      }
    },
    "stage": {
      "type": "string",
      "enum": [
        "alpha",
        "beta",
        "ga",
        "disabled"
      ]
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "name",
    "project_id",
    "role_id",
    "title",
    "description",
    "permissions",
    "stage",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Create custom role

`POST /v1/projects/{project_id}/roles`

#### Path parameters

- `project_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Request body

- `role_id` string (min length: 3; max length: 64; pattern: ^[a-z][a-zA-Z0-9._-]*$), required
- `title` string (min length: 1; max length: 100), required
- `description` string | null, required
- `permissions` string[] (min items: 1; max items: 100), required
- `stage` "alpha" | "beta" | "ga" | "disabled", required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "role_id": {
      "type": "string",
      "minLength": 3,
      "maxLength": 64,
      "pattern": "^[a-z][a-zA-Z0-9._-]*$"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "description": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 500
        },
        {
          "type": "null"
        }
      ]
    },
    "permissions": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 3,
        "maxLength": 256,
        "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
      }
    },
    "stage": {
      "type": "string",
      "enum": [
        "alpha",
        "beta",
        "ga",
        "disabled"
      ]
    }
  },
  "required": [
    "role_id",
    "title",
    "description",
    "permissions",
    "stage"
  ]
}
```

#### Response

- `name` string (min length: 7; max length: 256; pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$), required
- `project_id` custom, required
- `role_id` string (min length: 3; max length: 64; pattern: ^[a-z][a-zA-Z0-9._-]*$), required
- `title` string (min length: 1; max length: 100), required
- `description` string | null, required
- `permissions` string[] (min items: 1; max items: 100), required
- `stage` "alpha" | "beta" | "ga" | "disabled", required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 7,
      "maxLength": 256,
      "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
    },
    "project_id": {},
    "role_id": {
      "type": "string",
      "minLength": 3,
      "maxLength": 64,
      "pattern": "^[a-z][a-zA-Z0-9._-]*$"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "description": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 500
        },
        {
          "type": "null"
        }
      ]
    },
    "permissions": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 3,
        "maxLength": 256,
        "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
      }
    },
    "stage": {
      "type": "string",
      "enum": [
        "alpha",
        "beta",
        "ga",
        "disabled"
      ]
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "name",
    "project_id",
    "role_id",
    "title",
    "description",
    "permissions",
    "stage",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### List custom roles

`GET /v1/projects/{project_id}/roles`

#### Path parameters

- `project_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Query parameters


JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {}
}
```

#### Response

- `data` object[], required
  - `name` string (min length: 7; max length: 256; pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$), required
  - `project_id` custom, required
  - `role_id` string (min length: 3; max length: 64; pattern: ^[a-z][a-zA-Z0-9._-]*$), required
  - `title` string (min length: 1; max length: 100), required
  - `description` string | null, required
  - `permissions` string[] (min items: 1; max items: 100), required
  - `stage` "alpha" | "beta" | "ga" | "disabled", required
  - `created_at` custom, required
  - `updated_at` custom, required
- `has_more` false, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 7,
            "maxLength": 256,
            "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
          },
          "project_id": {},
          "role_id": {
            "type": "string",
            "minLength": 3,
            "maxLength": 64,
            "pattern": "^[a-z][a-zA-Z0-9._-]*$"
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "description": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 500
              },
              {
                "type": "null"
              }
            ]
          },
          "permissions": {
            "minItems": 1,
            "maxItems": 100,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 3,
              "maxLength": 256,
              "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
            }
          },
          "stage": {
            "type": "string",
            "enum": [
              "alpha",
              "beta",
              "ga",
              "disabled"
            ]
          },
          "created_at": {},
          "updated_at": {}
        },
        "required": [
          "name",
          "project_id",
          "role_id",
          "title",
          "description",
          "permissions",
          "stage",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    },
    "has_more": {
      "type": "boolean",
      "const": false
    }
  },
  "required": [
    "data",
    "has_more"
  ],
  "additionalProperties": false
}
```

### Get custom role

`GET /v1/projects/{project_id}/roles/{role_id}`

#### Path parameters

- `project_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

- `role_id` string (min length: 3; max length: 64; pattern: ^[a-z][a-zA-Z0-9._-]*$), required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "string",
  "minLength": 3,
  "maxLength": 64,
  "pattern": "^[a-z][a-zA-Z0-9._-]*$"
}
```


#### Response

- `name` string (min length: 7; max length: 256; pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$), required
- `project_id` custom, required
- `role_id` string (min length: 3; max length: 64; pattern: ^[a-z][a-zA-Z0-9._-]*$), required
- `title` string (min length: 1; max length: 100), required
- `description` string | null, required
- `permissions` string[] (min items: 1; max items: 100), required
- `stage` "alpha" | "beta" | "ga" | "disabled", required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 7,
      "maxLength": 256,
      "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
    },
    "project_id": {},
    "role_id": {
      "type": "string",
      "minLength": 3,
      "maxLength": 64,
      "pattern": "^[a-z][a-zA-Z0-9._-]*$"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "description": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 500
        },
        {
          "type": "null"
        }
      ]
    },
    "permissions": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 3,
        "maxLength": 256,
        "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
      }
    },
    "stage": {
      "type": "string",
      "enum": [
        "alpha",
        "beta",
        "ga",
        "disabled"
      ]
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "name",
    "project_id",
    "role_id",
    "title",
    "description",
    "permissions",
    "stage",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Update custom role

`PATCH /v1/projects/{project_id}/roles/{role_id}`

#### Path parameters

- `project_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

- `role_id` string (min length: 3; max length: 64; pattern: ^[a-z][a-zA-Z0-9._-]*$), required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "string",
  "minLength": 3,
  "maxLength": 64,
  "pattern": "^[a-z][a-zA-Z0-9._-]*$"
}
```


#### Request body

- `title` string (min length: 1; max length: 100), optional
- `description` string | null, optional
- `permissions` string[] (min items: 1; max items: 100), optional
- `stage` "alpha" | "beta" | "ga" | "disabled", optional

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "description": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 500
        },
        {
          "type": "null"
        }
      ]
    },
    "permissions": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 3,
        "maxLength": 256,
        "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
      }
    },
    "stage": {
      "type": "string",
      "enum": [
        "alpha",
        "beta",
        "ga",
        "disabled"
      ]
    }
  }
}
```

#### Response

- `name` string (min length: 7; max length: 256; pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$), required
- `project_id` custom, required
- `role_id` string (min length: 3; max length: 64; pattern: ^[a-z][a-zA-Z0-9._-]*$), required
- `title` string (min length: 1; max length: 100), required
- `description` string | null, required
- `permissions` string[] (min items: 1; max items: 100), required
- `stage` "alpha" | "beta" | "ga" | "disabled", required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 7,
      "maxLength": 256,
      "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
    },
    "project_id": {},
    "role_id": {
      "type": "string",
      "minLength": 3,
      "maxLength": 64,
      "pattern": "^[a-z][a-zA-Z0-9._-]*$"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "description": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 500
        },
        {
          "type": "null"
        }
      ]
    },
    "permissions": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 3,
        "maxLength": 256,
        "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
      }
    },
    "stage": {
      "type": "string",
      "enum": [
        "alpha",
        "beta",
        "ga",
        "disabled"
      ]
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "name",
    "project_id",
    "role_id",
    "title",
    "description",
    "permissions",
    "stage",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Delete custom role

`DELETE /v1/projects/{project_id}/roles/{role_id}`

#### Path parameters

- `project_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

- `role_id` string (min length: 3; max length: 64; pattern: ^[a-z][a-zA-Z0-9._-]*$), required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "string",
  "minLength": 3,
  "maxLength": 64,
  "pattern": "^[a-z][a-zA-Z0-9._-]*$"
}
```


#### Response

No response body.

## IAM policies

A GCP-style project IAM policy made of predefined role bindings.

### Resource schema

- `version` 1, required
- `etag` string (min length: 1), required
- `bindings` object[], required
  - `role` string (min length: 7; max length: 256; pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$), required
  - `members` string[] (min items: 1), required
  - `condition` object, optional
    - `title` string (min length: 1; max length: 100), required
    - `description` string | null, optional
    - `expression` string (min length: 1; max length: 1000), required
- `deny_rules` object[] (default: []), required
  - `denied_permissions` string[] (min items: 1; max items: 100), required
  - `denied_principals` string | "principalSet://socra/public:all"[] (min items: 1), required
  - `exception_principals` string[] (default: []), required
  - `condition` object, optional
    - `title` string (min length: 1; max length: 100), required
    - `description` string | null, optional
    - `expression` string (min length: 1; max length: 1000), required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "version": {
      "type": "number",
      "const": 1
    },
    "etag": {
      "type": "string",
      "minLength": 1
    },
    "bindings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "minLength": 7,
            "maxLength": 256,
            "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
          },
          "members": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            }
          },
          "condition": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "description": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 500
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "expression": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1000
              }
            },
            "required": [
              "title",
              "expression"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "role",
          "members"
        ],
        "additionalProperties": false
      }
    },
    "deny_rules": {
      "default": [],
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "denied_permissions": {
            "minItems": 1,
            "maxItems": 100,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 3,
              "maxLength": 256,
              "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
            }
          },
          "denied_principals": {
            "minItems": 1,
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string",
                  "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                },
                {
                  "type": "string",
                  "const": "principalSet://socra/public:all"
                }
              ]
            }
          },
          "exception_principals": {
            "default": [],
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            }
          },
          "condition": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "description": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 500
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "expression": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1000
              }
            },
            "required": [
              "title",
              "expression"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "denied_permissions",
          "denied_principals",
          "exception_principals"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "version",
    "etag",
    "bindings",
    "deny_rules"
  ],
  "additionalProperties": false
}
```

### Get IAM policy

`POST /v1/projects/{project_id}/iamPolicy/get`

#### Path parameters

- `project_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Request body


JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {}
}
```

#### Response

- `version` 1, required
- `etag` string (min length: 1), required
- `bindings` object[], required
  - `role` string (min length: 7; max length: 256; pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$), required
  - `members` string[] (min items: 1), required
  - `condition` object, optional
    - `title` string (min length: 1; max length: 100), required
    - `description` string | null, optional
    - `expression` string (min length: 1; max length: 1000), required
- `deny_rules` object[] (default: []), required
  - `denied_permissions` string[] (min items: 1; max items: 100), required
  - `denied_principals` string | "principalSet://socra/public:all"[] (min items: 1), required
  - `exception_principals` string[] (default: []), required
  - `condition` object, optional
    - `title` string (min length: 1; max length: 100), required
    - `description` string | null, optional
    - `expression` string (min length: 1; max length: 1000), required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "version": {
      "type": "number",
      "const": 1
    },
    "etag": {
      "type": "string",
      "minLength": 1
    },
    "bindings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "minLength": 7,
            "maxLength": 256,
            "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
          },
          "members": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            }
          },
          "condition": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "description": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 500
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "expression": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1000
              }
            },
            "required": [
              "title",
              "expression"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "role",
          "members"
        ],
        "additionalProperties": false
      }
    },
    "deny_rules": {
      "default": [],
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "denied_permissions": {
            "minItems": 1,
            "maxItems": 100,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 3,
              "maxLength": 256,
              "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
            }
          },
          "denied_principals": {
            "minItems": 1,
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string",
                  "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                },
                {
                  "type": "string",
                  "const": "principalSet://socra/public:all"
                }
              ]
            }
          },
          "exception_principals": {
            "default": [],
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            }
          },
          "condition": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "description": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 500
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "expression": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1000
              }
            },
            "required": [
              "title",
              "expression"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "denied_permissions",
          "denied_principals",
          "exception_principals"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "version",
    "etag",
    "bindings",
    "deny_rules"
  ],
  "additionalProperties": false
}
```

### Set IAM policy

`POST /v1/projects/{project_id}/iamPolicy/set`

#### Path parameters

- `project_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Request body

- `policy` object, required
  - `version` 1, required
  - `etag` string (min length: 1), required
  - `bindings` object[], required
    - `role` string (min length: 7; max length: 256; pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$), required
    - `members` string[] (min items: 1), required
    - `condition` object, optional
      - `title` string (min length: 1; max length: 100), required
      - `description` string | null, optional
      - `expression` string (min length: 1; max length: 1000), required
  - `deny_rules` object[] (default: []), optional
    - `denied_permissions` string[] (min items: 1; max items: 100), required
    - `denied_principals` string | "principalSet://socra/public:all"[] (min items: 1), required
    - `exception_principals` string[] (default: []), optional
    - `condition` object, optional
      - `title` string (min length: 1; max length: 100), required
      - `description` string | null, optional
      - `expression` string (min length: 1; max length: 1000), required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "policy": {
      "type": "object",
      "properties": {
        "version": {
          "type": "number",
          "const": 1
        },
        "etag": {
          "type": "string",
          "minLength": 1
        },
        "bindings": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "role": {
                "type": "string",
                "minLength": 7,
                "maxLength": 256,
                "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
              },
              "members": {
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                }
              },
              "condition": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "description": {
                    "anyOf": [
                      {
                        "type": "string",
                        "maxLength": 500
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "expression": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1000
                  }
                },
                "required": [
                  "title",
                  "expression"
                ]
              }
            },
            "required": [
              "role",
              "members"
            ]
          }
        },
        "deny_rules": {
          "default": [],
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "denied_permissions": {
                "minItems": 1,
                "maxItems": 100,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 3,
                  "maxLength": 256,
                  "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
                }
              },
              "denied_principals": {
                "minItems": 1,
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "type": "string",
                      "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                    },
                    {
                      "type": "string",
                      "const": "principalSet://socra/public:all"
                    }
                  ]
                }
              },
              "exception_principals": {
                "default": [],
                "type": "array",
                "items": {
                  "type": "string",
                  "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                }
              },
              "condition": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "description": {
                    "anyOf": [
                      {
                        "type": "string",
                        "maxLength": 500
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "expression": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1000
                  }
                },
                "required": [
                  "title",
                  "expression"
                ]
              }
            },
            "required": [
              "denied_permissions",
              "denied_principals"
            ]
          }
        }
      },
      "required": [
        "version",
        "etag",
        "bindings"
      ]
    }
  },
  "required": [
    "policy"
  ]
}
```

#### Response

- `version` 1, required
- `etag` string (min length: 1), required
- `bindings` object[], required
  - `role` string (min length: 7; max length: 256; pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$), required
  - `members` string[] (min items: 1), required
  - `condition` object, optional
    - `title` string (min length: 1; max length: 100), required
    - `description` string | null, optional
    - `expression` string (min length: 1; max length: 1000), required
- `deny_rules` object[] (default: []), required
  - `denied_permissions` string[] (min items: 1; max items: 100), required
  - `denied_principals` string | "principalSet://socra/public:all"[] (min items: 1), required
  - `exception_principals` string[] (default: []), required
  - `condition` object, optional
    - `title` string (min length: 1; max length: 100), required
    - `description` string | null, optional
    - `expression` string (min length: 1; max length: 1000), required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "version": {
      "type": "number",
      "const": 1
    },
    "etag": {
      "type": "string",
      "minLength": 1
    },
    "bindings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "minLength": 7,
            "maxLength": 256,
            "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
          },
          "members": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            }
          },
          "condition": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "description": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 500
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "expression": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1000
              }
            },
            "required": [
              "title",
              "expression"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "role",
          "members"
        ],
        "additionalProperties": false
      }
    },
    "deny_rules": {
      "default": [],
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "denied_permissions": {
            "minItems": 1,
            "maxItems": 100,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 3,
              "maxLength": 256,
              "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
            }
          },
          "denied_principals": {
            "minItems": 1,
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string",
                  "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                },
                {
                  "type": "string",
                  "const": "principalSet://socra/public:all"
                }
              ]
            }
          },
          "exception_principals": {
            "default": [],
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            }
          },
          "condition": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "description": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 500
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "expression": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1000
              }
            },
            "required": [
              "title",
              "expression"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "denied_permissions",
          "denied_principals",
          "exception_principals"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "version",
    "etag",
    "bindings",
    "deny_rules"
  ],
  "additionalProperties": false
}
```

### Test IAM permissions

`POST /v1/projects/{project_id}/iamPolicy/testPermissions`

#### Path parameters

- `project_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Request body

- `permissions` string[] (min items: 1; max items: 100), required
- `context` object, optional
  - `request_time` custom, optional
  - `resource_name` string (max length: 500), optional

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "permissions": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 3,
        "maxLength": 256,
        "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
      }
    },
    "context": {
      "type": "object",
      "properties": {
        "request_time": {},
        "resource_name": {
          "type": "string",
          "maxLength": 500
        }
      }
    }
  },
  "required": [
    "permissions"
  ]
}
```

#### Response

- `permissions` string[], required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "permissions": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 3,
        "maxLength": 256,
        "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
      }
    }
  },
  "required": [
    "permissions"
  ],
  "additionalProperties": false
}
```

## Account IAM policies

Inherited IAM allow and deny rules for every project in an account.

### Resource schema

- `version` 1, required
- `etag` string (min length: 1), required
- `bindings` object[], required
  - `role` string (min length: 7; max length: 256; pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$), required
  - `members` string[] (min items: 1), required
  - `condition` object, optional
    - `title` string (min length: 1; max length: 100), required
    - `description` string | null, optional
    - `expression` string (min length: 1; max length: 1000), required
- `deny_rules` object[] (default: []), required
  - `denied_permissions` string[] (min items: 1; max items: 100), required
  - `denied_principals` string | "principalSet://socra/public:all"[] (min items: 1), required
  - `exception_principals` string[] (default: []), required
  - `condition` object, optional
    - `title` string (min length: 1; max length: 100), required
    - `description` string | null, optional
    - `expression` string (min length: 1; max length: 1000), required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "version": {
      "type": "number",
      "const": 1
    },
    "etag": {
      "type": "string",
      "minLength": 1
    },
    "bindings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "minLength": 7,
            "maxLength": 256,
            "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
          },
          "members": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            }
          },
          "condition": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "description": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 500
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "expression": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1000
              }
            },
            "required": [
              "title",
              "expression"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "role",
          "members"
        ],
        "additionalProperties": false
      }
    },
    "deny_rules": {
      "default": [],
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "denied_permissions": {
            "minItems": 1,
            "maxItems": 100,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 3,
              "maxLength": 256,
              "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
            }
          },
          "denied_principals": {
            "minItems": 1,
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string",
                  "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                },
                {
                  "type": "string",
                  "const": "principalSet://socra/public:all"
                }
              ]
            }
          },
          "exception_principals": {
            "default": [],
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            }
          },
          "condition": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "description": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 500
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "expression": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1000
              }
            },
            "required": [
              "title",
              "expression"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "denied_permissions",
          "denied_principals",
          "exception_principals"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "version",
    "etag",
    "bindings",
    "deny_rules"
  ],
  "additionalProperties": false
}
```

### Get account IAM policy

`POST /v1/accounts/{account_id}/iamPolicy/get`

#### Path parameters

- `account_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Request body


JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {}
}
```

#### Response

- `version` 1, required
- `etag` string (min length: 1), required
- `bindings` object[], required
  - `role` string (min length: 7; max length: 256; pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$), required
  - `members` string[] (min items: 1), required
  - `condition` object, optional
    - `title` string (min length: 1; max length: 100), required
    - `description` string | null, optional
    - `expression` string (min length: 1; max length: 1000), required
- `deny_rules` object[] (default: []), required
  - `denied_permissions` string[] (min items: 1; max items: 100), required
  - `denied_principals` string | "principalSet://socra/public:all"[] (min items: 1), required
  - `exception_principals` string[] (default: []), required
  - `condition` object, optional
    - `title` string (min length: 1; max length: 100), required
    - `description` string | null, optional
    - `expression` string (min length: 1; max length: 1000), required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "version": {
      "type": "number",
      "const": 1
    },
    "etag": {
      "type": "string",
      "minLength": 1
    },
    "bindings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "minLength": 7,
            "maxLength": 256,
            "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
          },
          "members": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            }
          },
          "condition": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "description": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 500
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "expression": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1000
              }
            },
            "required": [
              "title",
              "expression"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "role",
          "members"
        ],
        "additionalProperties": false
      }
    },
    "deny_rules": {
      "default": [],
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "denied_permissions": {
            "minItems": 1,
            "maxItems": 100,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 3,
              "maxLength": 256,
              "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
            }
          },
          "denied_principals": {
            "minItems": 1,
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string",
                  "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                },
                {
                  "type": "string",
                  "const": "principalSet://socra/public:all"
                }
              ]
            }
          },
          "exception_principals": {
            "default": [],
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            }
          },
          "condition": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "description": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 500
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "expression": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1000
              }
            },
            "required": [
              "title",
              "expression"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "denied_permissions",
          "denied_principals",
          "exception_principals"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "version",
    "etag",
    "bindings",
    "deny_rules"
  ],
  "additionalProperties": false
}
```

### Set account IAM policy

`POST /v1/accounts/{account_id}/iamPolicy/set`

#### Path parameters

- `account_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Request body

- `policy` object, required
  - `version` 1, required
  - `etag` string (min length: 1), required
  - `bindings` object[], required
    - `role` string (min length: 7; max length: 256; pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$), required
    - `members` string[] (min items: 1), required
    - `condition` object, optional
      - `title` string (min length: 1; max length: 100), required
      - `description` string | null, optional
      - `expression` string (min length: 1; max length: 1000), required
  - `deny_rules` object[] (default: []), optional
    - `denied_permissions` string[] (min items: 1; max items: 100), required
    - `denied_principals` string | "principalSet://socra/public:all"[] (min items: 1), required
    - `exception_principals` string[] (default: []), optional
    - `condition` object, optional
      - `title` string (min length: 1; max length: 100), required
      - `description` string | null, optional
      - `expression` string (min length: 1; max length: 1000), required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "policy": {
      "type": "object",
      "properties": {
        "version": {
          "type": "number",
          "const": 1
        },
        "etag": {
          "type": "string",
          "minLength": 1
        },
        "bindings": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "role": {
                "type": "string",
                "minLength": 7,
                "maxLength": 256,
                "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
              },
              "members": {
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                }
              },
              "condition": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "description": {
                    "anyOf": [
                      {
                        "type": "string",
                        "maxLength": 500
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "expression": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1000
                  }
                },
                "required": [
                  "title",
                  "expression"
                ]
              }
            },
            "required": [
              "role",
              "members"
            ]
          }
        },
        "deny_rules": {
          "default": [],
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "denied_permissions": {
                "minItems": 1,
                "maxItems": 100,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 3,
                  "maxLength": 256,
                  "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
                }
              },
              "denied_principals": {
                "minItems": 1,
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "type": "string",
                      "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                    },
                    {
                      "type": "string",
                      "const": "principalSet://socra/public:all"
                    }
                  ]
                }
              },
              "exception_principals": {
                "default": [],
                "type": "array",
                "items": {
                  "type": "string",
                  "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                }
              },
              "condition": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "description": {
                    "anyOf": [
                      {
                        "type": "string",
                        "maxLength": 500
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "expression": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1000
                  }
                },
                "required": [
                  "title",
                  "expression"
                ]
              }
            },
            "required": [
              "denied_permissions",
              "denied_principals"
            ]
          }
        }
      },
      "required": [
        "version",
        "etag",
        "bindings"
      ]
    }
  },
  "required": [
    "policy"
  ]
}
```

#### Response

- `version` 1, required
- `etag` string (min length: 1), required
- `bindings` object[], required
  - `role` string (min length: 7; max length: 256; pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$), required
  - `members` string[] (min items: 1), required
  - `condition` object, optional
    - `title` string (min length: 1; max length: 100), required
    - `description` string | null, optional
    - `expression` string (min length: 1; max length: 1000), required
- `deny_rules` object[] (default: []), required
  - `denied_permissions` string[] (min items: 1; max items: 100), required
  - `denied_principals` string | "principalSet://socra/public:all"[] (min items: 1), required
  - `exception_principals` string[] (default: []), required
  - `condition` object, optional
    - `title` string (min length: 1; max length: 100), required
    - `description` string | null, optional
    - `expression` string (min length: 1; max length: 1000), required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "version": {
      "type": "number",
      "const": 1
    },
    "etag": {
      "type": "string",
      "minLength": 1
    },
    "bindings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "minLength": 7,
            "maxLength": 256,
            "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
          },
          "members": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            }
          },
          "condition": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "description": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 500
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "expression": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1000
              }
            },
            "required": [
              "title",
              "expression"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "role",
          "members"
        ],
        "additionalProperties": false
      }
    },
    "deny_rules": {
      "default": [],
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "denied_permissions": {
            "minItems": 1,
            "maxItems": 100,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 3,
              "maxLength": 256,
              "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
            }
          },
          "denied_principals": {
            "minItems": 1,
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string",
                  "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                },
                {
                  "type": "string",
                  "const": "principalSet://socra/public:all"
                }
              ]
            }
          },
          "exception_principals": {
            "default": [],
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            }
          },
          "condition": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "description": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 500
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "expression": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1000
              }
            },
            "required": [
              "title",
              "expression"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "denied_permissions",
          "denied_principals",
          "exception_principals"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "version",
    "etag",
    "bindings",
    "deny_rules"
  ],
  "additionalProperties": false
}
```

## IAM policy audit events

Immutable history of project IAM policy mutations.

### Resource schema

- `id` string, required
- `project_id` custom, required
- `actor_principal` string (pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$), required
- `action` "policy.bootstrap" | "policy.set", required
- `previous_policy` object | null, required
- `policy` object, required
  - `version` 1, required
  - `etag` string (min length: 1), required
  - `bindings` object[], required
    - `role` string (min length: 7; max length: 256; pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$), required
    - `members` string[] (min items: 1), required
    - `condition` object, optional
      - `title` string (min length: 1; max length: 100), required
      - `description` string | null, optional
      - `expression` string (min length: 1; max length: 1000), required
  - `deny_rules` object[] (default: []), required
    - `denied_permissions` string[] (min items: 1; max items: 100), required
    - `denied_principals` string | "principalSet://socra/public:all"[] (min items: 1), required
    - `exception_principals` string[] (default: []), required
    - `condition` object, optional
      - `title` string (min length: 1; max length: 100), required
      - `description` string | null, optional
      - `expression` string (min length: 1; max length: 1000), required
- `created_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "project_id": {},
    "actor_principal": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "action": {
      "type": "string",
      "enum": [
        "policy.bootstrap",
        "policy.set"
      ]
    },
    "previous_policy": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "version": {
              "type": "number",
              "const": 1
            },
            "etag": {
              "type": "string",
              "minLength": 1
            },
            "bindings": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "role": {
                    "type": "string",
                    "minLength": 7,
                    "maxLength": 256,
                    "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
                  },
                  "members": {
                    "minItems": 1,
                    "type": "array",
                    "items": {
                      "type": "string",
                      "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                    }
                  },
                  "condition": {
                    "type": "object",
                    "properties": {
                      "title": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 100
                      },
                      "description": {
                        "anyOf": [
                          {
                            "type": "string",
                            "maxLength": 500
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "expression": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 1000
                      }
                    },
                    "required": [
                      "title",
                      "expression"
                    ],
                    "additionalProperties": false
                  }
                },
                "required": [
                  "role",
                  "members"
                ],
                "additionalProperties": false
              }
            },
            "deny_rules": {
              "default": [],
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "denied_permissions": {
                    "minItems": 1,
                    "maxItems": 100,
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 3,
                      "maxLength": 256,
                      "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
                    }
                  },
                  "denied_principals": {
                    "minItems": 1,
                    "type": "array",
                    "items": {
                      "anyOf": [
                        {
                          "type": "string",
                          "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                        },
                        {
                          "type": "string",
                          "const": "principalSet://socra/public:all"
                        }
                      ]
                    }
                  },
                  "exception_principals": {
                    "default": [],
                    "type": "array",
                    "items": {
                      "type": "string",
                      "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                    }
                  },
                  "condition": {
                    "type": "object",
                    "properties": {
                      "title": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 100
                      },
                      "description": {
                        "anyOf": [
                          {
                            "type": "string",
                            "maxLength": 500
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "expression": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 1000
                      }
                    },
                    "required": [
                      "title",
                      "expression"
                    ],
                    "additionalProperties": false
                  }
                },
                "required": [
                  "denied_permissions",
                  "denied_principals",
                  "exception_principals"
                ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "version",
            "etag",
            "bindings",
            "deny_rules"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "policy": {
      "type": "object",
      "properties": {
        "version": {
          "type": "number",
          "const": 1
        },
        "etag": {
          "type": "string",
          "minLength": 1
        },
        "bindings": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "role": {
                "type": "string",
                "minLength": 7,
                "maxLength": 256,
                "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
              },
              "members": {
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                }
              },
              "condition": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "description": {
                    "anyOf": [
                      {
                        "type": "string",
                        "maxLength": 500
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "expression": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1000
                  }
                },
                "required": [
                  "title",
                  "expression"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "role",
              "members"
            ],
            "additionalProperties": false
          }
        },
        "deny_rules": {
          "default": [],
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "denied_permissions": {
                "minItems": 1,
                "maxItems": 100,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 3,
                  "maxLength": 256,
                  "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
                }
              },
              "denied_principals": {
                "minItems": 1,
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "type": "string",
                      "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                    },
                    {
                      "type": "string",
                      "const": "principalSet://socra/public:all"
                    }
                  ]
                }
              },
              "exception_principals": {
                "default": [],
                "type": "array",
                "items": {
                  "type": "string",
                  "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                }
              },
              "condition": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "description": {
                    "anyOf": [
                      {
                        "type": "string",
                        "maxLength": 500
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "expression": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1000
                  }
                },
                "required": [
                  "title",
                  "expression"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "denied_permissions",
              "denied_principals",
              "exception_principals"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "version",
        "etag",
        "bindings",
        "deny_rules"
      ],
      "additionalProperties": false
    },
    "created_at": {}
  },
  "required": [
    "id",
    "project_id",
    "actor_principal",
    "action",
    "previous_policy",
    "policy",
    "created_at"
  ],
  "additionalProperties": false
}
```

### List IAM policy audit history

`GET /v1/projects/{project_id}/iamPolicy/audit`

#### Path parameters

- `project_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Query parameters

- `limit` integer (min: 1; max: 100), optional

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}
```

#### Response

- `data` object[], required
  - `id` string, required
  - `project_id` custom, required
  - `actor_principal` string (pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$), required
  - `action` "policy.bootstrap" | "policy.set", required
  - `previous_policy` object | null, required
  - `policy` object, required
    - `version` 1, required
    - `etag` string (min length: 1), required
    - `bindings` object[], required
      - `role` string (min length: 7; max length: 256; pattern: ^(?:roles\/[a-z][a-zA-Z0-9._-]*|projects\/proj_[a-z0-9]+\/roles\/[a-z][a-zA-Z0-9._-]*)$), required
      - `members` string[] (min items: 1), required
      - `condition` object, optional
        - `title` string (min length: 1; max length: 100), required
        - `description` string | null, optional
        - `expression` string (min length: 1; max length: 1000), required
    - `deny_rules` object[] (default: []), required
      - `denied_permissions` string[] (min items: 1; max items: 100), required
      - `denied_principals` string | "principalSet://socra/public:all"[] (min items: 1), required
      - `exception_principals` string[] (default: []), required
      - `condition` object, optional
        - `title` string (min length: 1; max length: 100), required
        - `description` string | null, optional
        - `expression` string (min length: 1; max length: 1000), required
  - `created_at` custom, required
- `has_more` boolean, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "project_id": {},
          "actor_principal": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          },
          "action": {
            "type": "string",
            "enum": [
              "policy.bootstrap",
              "policy.set"
            ]
          },
          "previous_policy": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "version": {
                    "type": "number",
                    "const": 1
                  },
                  "etag": {
                    "type": "string",
                    "minLength": 1
                  },
                  "bindings": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "role": {
                          "type": "string",
                          "minLength": 7,
                          "maxLength": 256,
                          "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
                        },
                        "members": {
                          "minItems": 1,
                          "type": "array",
                          "items": {
                            "type": "string",
                            "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                          }
                        },
                        "condition": {
                          "type": "object",
                          "properties": {
                            "title": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 100
                            },
                            "description": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "maxLength": 500
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "expression": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 1000
                            }
                          },
                          "required": [
                            "title",
                            "expression"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "required": [
                        "role",
                        "members"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "deny_rules": {
                    "default": [],
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "denied_permissions": {
                          "minItems": 1,
                          "maxItems": 100,
                          "type": "array",
                          "items": {
                            "type": "string",
                            "minLength": 3,
                            "maxLength": 256,
                            "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
                          }
                        },
                        "denied_principals": {
                          "minItems": 1,
                          "type": "array",
                          "items": {
                            "anyOf": [
                              {
                                "type": "string",
                                "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                              },
                              {
                                "type": "string",
                                "const": "principalSet://socra/public:all"
                              }
                            ]
                          }
                        },
                        "exception_principals": {
                          "default": [],
                          "type": "array",
                          "items": {
                            "type": "string",
                            "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                          }
                        },
                        "condition": {
                          "type": "object",
                          "properties": {
                            "title": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 100
                            },
                            "description": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "maxLength": 500
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "expression": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 1000
                            }
                          },
                          "required": [
                            "title",
                            "expression"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "required": [
                        "denied_permissions",
                        "denied_principals",
                        "exception_principals"
                      ],
                      "additionalProperties": false
                    }
                  }
                },
                "required": [
                  "version",
                  "etag",
                  "bindings",
                  "deny_rules"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "policy": {
            "type": "object",
            "properties": {
              "version": {
                "type": "number",
                "const": 1
              },
              "etag": {
                "type": "string",
                "minLength": 1
              },
              "bindings": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "role": {
                      "type": "string",
                      "minLength": 7,
                      "maxLength": 256,
                      "pattern": "^(?:roles\\/[a-z][a-zA-Z0-9._-]*|projects\\/proj_[a-z0-9]+\\/roles\\/[a-z][a-zA-Z0-9._-]*)$"
                    },
                    "members": {
                      "minItems": 1,
                      "type": "array",
                      "items": {
                        "type": "string",
                        "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                      }
                    },
                    "condition": {
                      "type": "object",
                      "properties": {
                        "title": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 100
                        },
                        "description": {
                          "anyOf": [
                            {
                              "type": "string",
                              "maxLength": 500
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "expression": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 1000
                        }
                      },
                      "required": [
                        "title",
                        "expression"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "role",
                    "members"
                  ],
                  "additionalProperties": false
                }
              },
              "deny_rules": {
                "default": [],
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "denied_permissions": {
                      "minItems": 1,
                      "maxItems": 100,
                      "type": "array",
                      "items": {
                        "type": "string",
                        "minLength": 3,
                        "maxLength": 256,
                        "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
                      }
                    },
                    "denied_principals": {
                      "minItems": 1,
                      "type": "array",
                      "items": {
                        "anyOf": [
                          {
                            "type": "string",
                            "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                          },
                          {
                            "type": "string",
                            "const": "principalSet://socra/public:all"
                          }
                        ]
                      }
                    },
                    "exception_principals": {
                      "default": [],
                      "type": "array",
                      "items": {
                        "type": "string",
                        "pattern": "^(principal|group):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                      }
                    },
                    "condition": {
                      "type": "object",
                      "properties": {
                        "title": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 100
                        },
                        "description": {
                          "anyOf": [
                            {
                              "type": "string",
                              "maxLength": 500
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "expression": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 1000
                        }
                      },
                      "required": [
                        "title",
                        "expression"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "denied_permissions",
                    "denied_principals",
                    "exception_principals"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "required": [
              "version",
              "etag",
              "bindings",
              "deny_rules"
            ],
            "additionalProperties": false
          },
          "created_at": {}
        },
        "required": [
          "id",
          "project_id",
          "actor_principal",
          "action",
          "previous_policy",
          "policy",
          "created_at"
        ],
        "additionalProperties": false
      }
    },
    "has_more": {
      "type": "boolean"
    }
  },
  "required": [
    "data",
    "has_more"
  ],
  "additionalProperties": false
}
```

## IAM authorization metrics

Per-permission authorization check, allow, and denial counters.

### Resource schema

- `permission` string (min length: 3; max length: 256; pattern: ^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$), required
- `checks` integer (min: 0; max: 9007199254740991), required
- `allowed` integer (min: 0; max: 9007199254740991), required
- `denied` integer (min: 0; max: 9007199254740991), required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "permission": {
      "type": "string",
      "minLength": 3,
      "maxLength": 256,
      "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
    },
    "checks": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "allowed": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "denied": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "permission",
    "checks",
    "allowed",
    "denied"
  ],
  "additionalProperties": false
}
```

### List IAM authorization metrics

`GET /v1/projects/{project_id}/iamPolicy/metrics`

#### Path parameters

- `project_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Query parameters


JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {}
}
```

#### Response

- `data` object[], required
  - `permission` string (min length: 3; max length: 256; pattern: ^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$), required
  - `checks` integer (min: 0; max: 9007199254740991), required
  - `allowed` integer (min: 0; max: 9007199254740991), required
  - `denied` integer (min: 0; max: 9007199254740991), required
- `has_more` false, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "permission": {
            "type": "string",
            "minLength": 3,
            "maxLength": 256,
            "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z][a-zA-Z0-9]*)+$"
          },
          "checks": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "allowed": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "denied": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "permission",
          "checks",
          "allowed",
          "denied"
        ],
        "additionalProperties": false
      }
    },
    "has_more": {
      "type": "boolean",
      "const": false
    }
  },
  "required": [
    "data",
    "has_more"
  ],
  "additionalProperties": false
}
```

## Service accounts

A project-owned non-human identity.

### Resource schema

- `id` custom, required
- `project_id` custom, required
- `principal_id` string | null, required
- `name` string (min length: 1; max length: 48; pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$), required
- `status` "active" | "disabled", required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "project_id": {},
    "principal_id": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 48,
      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ]
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "project_id",
    "principal_id",
    "name",
    "status",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Create service account

`POST /v1/projects/{project_id}/service-accounts`

#### Path parameters

- `project_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Request body

- `name` string (min length: 1; max length: 48; pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$), required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 48,
      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
    }
  },
  "required": [
    "name"
  ]
}
```

#### Response

- `id` custom, required
- `project_id` custom, required
- `principal_id` string | null, required
- `name` string (min length: 1; max length: 48; pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$), required
- `status` "active" | "disabled", required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "project_id": {},
    "principal_id": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 48,
      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ]
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "project_id",
    "principal_id",
    "name",
    "status",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### List service accounts

`GET /v1/projects/{project_id}/service-accounts`

#### Path parameters

- `project_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Query parameters

- `limit` integer (min: 1; max: 100), optional
- `after` string, optional

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "after": {
      "type": "string"
    }
  }
}
```

#### Response

- `data` object[], required
  - `id` custom, required
  - `project_id` custom, required
  - `principal_id` string | null, required
  - `name` string (min length: 1; max length: 48; pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$), required
  - `status` "active" | "disabled", required
  - `created_at` custom, required
  - `updated_at` custom, required
- `has_more` boolean, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {},
          "project_id": {},
          "principal_id": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
              },
              {
                "type": "null"
              }
            ]
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 48,
            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "disabled"
            ]
          },
          "created_at": {},
          "updated_at": {}
        },
        "required": [
          "id",
          "project_id",
          "principal_id",
          "name",
          "status",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    },
    "has_more": {
      "type": "boolean"
    }
  },
  "required": [
    "data",
    "has_more"
  ],
  "additionalProperties": false
}
```

### Get service account

`GET /v1/projects/{project_id}/service-accounts/{service_account_id}`

#### Path parameters

- `project_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

- `service_account_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

- `id` custom, required
- `project_id` custom, required
- `principal_id` string | null, required
- `name` string (min length: 1; max length: 48; pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$), required
- `status` "active" | "disabled", required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "project_id": {},
    "principal_id": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 48,
      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ]
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "project_id",
    "principal_id",
    "name",
    "status",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Update service account

`PATCH /v1/projects/{project_id}/service-accounts/{service_account_id}`

#### Path parameters

- `project_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

- `service_account_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Request body

- `status` "active" | "disabled", optional

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ]
    }
  }
}
```

#### Response

- `id` custom, required
- `project_id` custom, required
- `principal_id` string | null, required
- `name` string (min length: 1; max length: 48; pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$), required
- `status` "active" | "disabled", required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "project_id": {},
    "principal_id": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 48,
      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ]
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "project_id",
    "principal_id",
    "name",
    "status",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Delete service account

`DELETE /v1/projects/{project_id}/service-accounts/{service_account_id}`

#### Path parameters

- `project_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

- `service_account_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

No response body.

## Service account keys

A replaceable credential for a service account.

### Resource schema

- `id` custom, required
- `service_account_id` custom, required
- `secret_hint` string, required
- `secret` string, optional
- `created_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "service_account_id": {},
    "secret_hint": {
      "type": "string"
    },
    "secret": {
      "type": "string"
    },
    "created_at": {}
  },
  "required": [
    "id",
    "service_account_id",
    "secret_hint",
    "created_at"
  ],
  "additionalProperties": false
}
```

### Create service account key

`POST /v1/projects/{project_id}/service-accounts/{service_account_id}/keys`

#### Path parameters

- `project_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

- `service_account_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Request body


JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {}
}
```

#### Response

- `id` custom, required
- `service_account_id` custom, required
- `secret_hint` string, required
- `secret` string, optional
- `created_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "service_account_id": {},
    "secret_hint": {
      "type": "string"
    },
    "secret": {
      "type": "string"
    },
    "created_at": {}
  },
  "required": [
    "id",
    "service_account_id",
    "secret_hint",
    "created_at"
  ],
  "additionalProperties": false
}
```

### List service account keys

`GET /v1/projects/{project_id}/service-accounts/{service_account_id}/keys`

#### Path parameters

- `project_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

- `service_account_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Query parameters


JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {}
}
```

#### Response

- `data` object[], required
  - `id` custom, required
  - `service_account_id` custom, required
  - `secret_hint` string, required
  - `secret` string, optional
  - `created_at` custom, required
- `has_more` boolean, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {},
          "service_account_id": {},
          "secret_hint": {
            "type": "string"
          },
          "secret": {
            "type": "string"
          },
          "created_at": {}
        },
        "required": [
          "id",
          "service_account_id",
          "secret_hint",
          "created_at"
        ],
        "additionalProperties": false
      }
    },
    "has_more": {
      "type": "boolean"
    }
  },
  "required": [
    "data",
    "has_more"
  ],
  "additionalProperties": false
}
```

### Delete service account key

`DELETE /v1/projects/{project_id}/service-accounts/{service_account_id}/keys/{key_id}`

#### Path parameters

- `project_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

- `service_account_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

- `key_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

No response body.

---

Company: Socra — Multiply Your Judgment
Canonical URL: https://cloud.socra.com/docs/iam/reference/api