openapi: 3.0.3
info:
  title: Cloudinary Account Provisioning API
  version: 0.2.1 # x-release-please-version
  description: |
    Accounts with provisioning API access can create and manage their **product environments**, **users** and **user groups** using the RESTful Provisioning API.

    Provisioning API access is available [upon request](https://cloudinary.com/contact?plan=enterprise) for accounts on an [Enterprise plan](https://cloudinary.com/pricing#pricing-enterprise).

    The API uses **Basic Authentication** over HTTPS. Your **Account API Key** and **Account API Secret** (previously referred to as **Provisioning API keys**) are used for the authentication. These credentials (as well as your ACCOUNT_ID) are located in the [Cloudinary Console](https://console.cloudinary.com/pm) under **Settings > Account API Keys**.

    The Provisioning API has dedicated SDKs for the following languages:

    * [JavaScript](https://github.com/cloudinary/account-provisioning-js)
    * [PHP](https://github.com/cloudinary/account-provisioning-php)
    * [Java](https://github.com/cloudinary/account-provisioning-java)

    Useful links:
    * [Provisioning API reference (Classic)](https://cloudinary.com/documentation/provisioning_api_1) (includes SDKs for additional languages)

    Accounts with Permissions API access can assign roles, made up of system policies, to control what principals (users, groups, and API keys) can do across the Cloudinary account and product environments. For more information about Cloudinary roles and permissions, see the [Role-based permissions](permissions_overview) guide.

    Permissions API access is available [upon request](https://cloudinary.com/contact?plan=enterprise) for accounts on an [Enterprise plan](https://cloudinary.com/pricing#pricing-enterprise).

    The API uses **Basic Authentication** over HTTPS. Your **Account API Key** and **Account API Secret** (previously referred to as **Provisioning API keys**) are used for the authentication. These credentials (as well as your ACCOUNT_ID) are located in the [Cloudinary Console](https://console.cloudinary.com/app/settings/account-api-keys) under **Settings > Account API Keys**.

    _**Important:**_

    _Cloudinary's **Roles and Permissions Management** is now available as a **Beta**. This is an early stage release, and while it's functional and ready for real-world testing, it's subject to change as we continue refining the experience based on what we learn, including your feedback.
    During the Beta period, core functionality is considered stable, though some APIs, scopes, or response formats may evolve._

    _**How you can help:**_

    * _Use Roles and Permissions Management in real projects, prototypes, or tests._
    * _Share feedback, issues, or ideas with our support team._

    _Thank you for exploring this early release and helping us shape these tools to best meet your needs._

  contact:
    name: Cloudinary Support
    email: support@cloudinary.com
    url: https://support.cloudinary.com
  termsOfService: https://cloudinary.com/tou
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  x-cld-module-context: account
  x-cld-module-name: account-provisioning

servers:
  - url: https://{region}.cloudinary.com
    description: Regional API endpoints for optimal performance.
    variables:
      region:
        default: api
        description: Regional endpoint selection
        enum:
          - api
          - api-eu
          - api-ap
  - url: https://{host}
    description: Custom domains for enterprise deployments.
    variables:
      host:
        default: api.cloudinary.com
        description: API host domain.

tags:
  - name: Product Environments
    description: |
      Manage the product environments (sub-accounts) of your main account.
    externalDocs:
      description: Learn more about product environments management.
      url: https://cloudinary.com/documentation/provisioning_api#product_environments
  - name: Access Keys
    description: |
      Manage the access keys, which include an API key and secret pair, for your product environment (sub-account).
    externalDocs:
      description: Learn more about access keys management.
      url: https://cloudinary.com/documentation/provisioning_api#access_keys
  - name: Users
    description: |
      Manage the users for your account.
    externalDocs:
      description: Learn more about users management.
      url: https://cloudinary.com/documentation/provisioning_api#users
  - name: User Groups
    description: |
      Manage the groups for the users in your account
    externalDocs:
      description: Learn more about user groups management.
      url: https://cloudinary.com/documentation/provisioning_api#user_groups
  - name: Billing Usage
    description: |
      Access billing usage information for your account and product environments.
    externalDocs:
      description: Learn more about billing and usage information.
      url: https://cloudinary.com/documentation/provisioning_api#billing_usage

  - name: System Policies
    description: |
      View all system policies predefined by Cloudinary, which can be associated with roles.
  - name: Roles
    description: |
      All roles include one or more predefined **system policies**, and can be applied to principals to enforce these policies.

      You can **manage custom roles**, where you select the system policies.

      You can **view system roles**, which contain a fixed set of system policies and are provided by Cloudinary.

  - name: Custom Policies
    description: |
      View and manage the custom policies that control permissions in your account and product environments. Each policy includes a statement defined in Cedar.

      For more information on writing Cedar statements for custom policies, see the [Cedar official documentation](https://docs.cedarpolicy.com/).
  - name: Effective Policies
    description: |
      View all the system and custom policies that are granted to a principal.

  - name: Principals
    description: |
      View roles associated with a specified principal, and add or remove a role associated with a principal.

  - name: Public
    description: |
      View shared Permissions system utilities, including the system roles and policies catalog, Cedar policy validation, and the Cedar schema. These endpoints are publicly accessible and don't require authentication.


# -----------------------------------------------------------------------

security:
  - basicAuth: []

paths:
  /v1_1/provisioning/accounts/{account_id}/sub_accounts:
    parameters:
      - $ref: '#/components/parameters/AccountIdParam'
    get:
      tags:
        - Product Environments
      summary: Get product environments
      description: |
        Return an array of all product environments, or if conditions are specified,
        return the relevant product environments.
      externalDocs:
        description: Learn more about getting product environments.
        url: https://cloudinary.com/documentation/provisioning_api#get_product_environments
      operationId: getProductEnvironments
      x-cld-use-for-readme: true
      parameters:
        - name: enabled
          in: query
          schema:
            type: boolean
          description: |
            Whether to only return enabled product environments (true) or disabled product environments (false).
            **Default**: all product environments are returned (both enabled and disabled).
          example: true
        - name: ids
          in: query
          schema:
            type: array
            items:
              type: string
          description: A list of up to 100 product environment IDs. When provided, other parameters are ignored.
        - name: cloud_names
          in: query
          schema:
            type: array
            items:
              type: string
          description: A list of up to 100 product environment cloud names.
        - name: prefix
          in: query
          schema:
            type: string
          description: Returns product environments where the name begins with the specified case-insensitive string.
          example: "product"
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductEnvironmentsResponse"
              examples:
                ProductEnvironments:
                  $ref: "#/components/examples/ProductEnvironments"
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403NotAllowed'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409AlreadyExists'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'

    post:
      tags:
        - Product Environments
      summary: Create product environment
      description: |
        Create a new product environment. Any users that have access to all product environments will also automatically
        have access to the new product environment.
      externalDocs:
        description: Learn more about creating product environments.
        url: https://cloudinary.com/documentation/provisioning_api#create_product_environment
      operationId: createProductEnvironment
      requestBody:
        required: true
        description: Product environment details.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProductEnvironmentRequest"
      responses:
        '200':
          description: Product environment created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductEnvironment"
              examples:
                ProductEnvironment3:
                  $ref: '#/components/examples/ProductEnvironment3'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403NotAllowed'
        '409':
          $ref: '#/components/responses/409AlreadyExists'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'

  /v1_1/provisioning/accounts/{account_id}/sub_accounts/{sub_account_id}:
    parameters:
      - $ref: '#/components/parameters/AccountIdParam'
      - $ref: '#/components/parameters/subAccountId'

    get:
      tags:
        - Product Environments
      summary: Get product environment
      description: Retrieve a specific product environment.
      externalDocs:
        description: Learn more about retrieving specific product environments.
        url: https://cloudinary.com/documentation/provisioning_api#get_product_environment
      operationId: getProductEnvironment
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductEnvironment"
              examples:
                ProductEnvironment1:
                  $ref: '#/components/examples/ProductEnvironment1'
                ProductEnvironment2:
                  $ref: '#/components/examples/ProductEnvironment2'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '404':
          $ref: '#/components/responses/404NotFound'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'

    put:
      tags:
        - Product Environments
      summary: Update product environment
      description: Update the details of a product environment.
      externalDocs:
        description: Learn more about updating product environments.
        url: https://cloudinary.com/documentation/provisioning_api#update_product_environment
      operationId: updateProductEnvironment
      requestBody:
        required: true
        description: Product environment details to update.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProductEnvironmentUpdateRequest"
      responses:
        '200':
          description: Product environment updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductEnvironment"
              examples:
                ProductEnvironment1:
                  $ref: '#/components/examples/ProductEnvironment1'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403NotAllowed'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409AlreadyExists'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
    delete:
      tags:
        - Product Environments
      summary: Delete product environment
      description: Delete a specific product environment.
      externalDocs:
        description: Learn more about deleting product environments.
        url: https://cloudinary.com/documentation/provisioning_api#delete_product_environment
      operationId: deleteProductEnvironment
      responses:
        '200':
          description: Product environment deleted successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403NotAllowed'
        '404':
          $ref: '#/components/responses/404NotFound'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'

  /v1_1/provisioning/accounts/{account_id}/sub_accounts/{sub_account_id}/access_keys:
    parameters:
      - $ref: '#/components/parameters/AccountIdParam'
      - $ref: '#/components/parameters/subAccountId'

    get:
      tags:
        - Access Keys
      summary: Get access keys
      description: Retrieve an array of all access keys for a product environment.
      externalDocs:
        description: Learn more about retrieving access keys.
        url: https://cloudinary.com/documentation/provisioning_api#get_access_keys
      operationId: getAccessKeys
      parameters:
        - name: page_size
          in: query
          schema:
            type: integer
          description: How many entries to display on each page.
        - name: page
          in: query
          schema:
            type: integer
            maximum: 100
          description: |
            Which page to return (maximum pages 100). **Default**: All pages are returned.
        - name: sort_by
          in: query
          schema:
            type: string
            enum:
              - api_key
              - created_at
              - name
              - enabled
          description: |
            Which response parameter to sort by. **Possible values**: `api_key`, `created_at`, `name`, `enabled`.
          example: created_at
        - name: sort_order
          in: query
          schema:
            type: string
            enum:
              - desc
              - asc
          description: |
            Control the order of returned keys. **Possible values**: `desc` (default), `asc`.
          example: asc
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccessKeysResponse"
              examples:
                AccessKeys:
                  $ref: "#/components/examples/AccessKeys"
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '404':
          $ref: '#/components/responses/404NotFound'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
    post:
      tags:
        - Access Keys
      summary: Generate an access key
      description: Generate a new access key.
      externalDocs:
        description: Learn more about generating access keys.
        url: https://cloudinary.com/documentation/provisioning_api#generate_an_access_key
      operationId: generateAccessKey
      requestBody:
        required: true
        description: Access key details.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccessKeyRequest"
      responses:
        '200':
          description: Access key created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccessKey"
              examples:
                MainAccessKey:
                  $ref: "#/components/examples/MainAccessKey"
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403NotAllowed'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409AlreadyExists'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'

    delete:
      tags:
        - Access Keys
      summary: Delete access key by name
      description: Delete a specific access key by name.
      externalDocs:
        description: Learn more about deleting access keys.
        url: https://cloudinary.com/documentation/provisioning_api#delete_an_access_key
      operationId: deleteAccessKeyByName
      parameters:
        - name: name
          description: The access key name.
          in: query
          required: true
          schema:
            type: string
          example: "main_key"
      responses:
        '200':
          description: Access Key deleted successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403NotAllowed'
        '404':
          $ref: '#/components/responses/404NotFound'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'

  /v1_1/provisioning/accounts/{account_id}/sub_accounts/{sub_account_id}/access_keys/{key}:
    parameters:
      - $ref: '#/components/parameters/AccountIdParam'
      - $ref: '#/components/parameters/subAccountId'
      - $ref: '#/components/parameters/accessKey'

    put:
      tags:
        - Access Keys
      summary: Update an access key
      description: Update the name and/or status of an existing access key.
      externalDocs:
        description: Learn more about updating access keys.
        url: https://cloudinary.com/documentation/provisioning_api#update_an_access_key
      operationId: updateAccessKey
      requestBody:
        required: true
        description: Access key details for update.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccessKeyUpdateRequest"
      responses:
        '200':
          description: Access key updated successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccessKey"
              examples:
                MainAccessKey:
                  $ref: "#/components/examples/MainAccessKey"
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403NotAllowed'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409AlreadyExists'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
    delete:
      tags:
        - Access Keys
      summary: Delete access key
      description: Delete a specific access key.
      externalDocs:
        description: Learn more about deleting access keys.
        url: https://cloudinary.com/documentation/provisioning_api#delete_an_access_key
      operationId: deleteAccessKey
      responses:
        '200':
          description: Access key deleted successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403NotAllowed'
        '404':
          $ref: '#/components/responses/404NotFound'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'

  /v1_1/provisioning/accounts/{account_id}/users:
    parameters:
      - $ref: '#/components/parameters/AccountIdParam'
    get:
      summary: Get users
      description: |
        Returns an array of all users in the account, or if conditions are specified, returns the relevant users.
      externalDocs:
        description: Learn more about retrieving users.
        url: https://cloudinary.com/documentation/provisioning_api#get_users
      operationId: getUsers
      tags:
        - Users
      parameters:
        - name: pending
          in: query
          schema:
            type: boolean
          description: |
            Whether to return pending users. **Default**: `false` (all users)
          example: false
        - name: ids
          in: query
          schema:
            type: array
            items:
              type: string
            maxItems: 100
          description: A list of up to 100 user IDs.  When provided, other parameters are ignored.
        - name: emails
          in: query
          schema:
            type: array
            items:
              type: string
            maxItems: 100
          description: A list of up to 100 user Emails.  When provided, other parameters are ignored.
        - name: prefix
          in: query
          schema:
            type: string
          description: Returns users where the name begins with the specified case-insensitive string.
          example: 'john'
        - name: sub_account_id
          in: query
          schema:
            type: string
          description: Only returns users who have access to the specified account.
        - name: last_login
          in: query
          description: Specifies a date range for last login.
          schema:
            type: boolean
        - name: from
          in: query
          description: |
            All last logins after this date, given in the format: yyyy-mm-dd.
          schema:
            type: string
            format: date
          example: 2023-01-01
        - name: to
          in: query
          description: |
            All last logins before this date, given in the format: yyyy-mm-dd.
          schema:
            type: string
            format: date
          example: 2024-12-31
        - name: union_type
          in: query
          description: |
            Whether to return users who last logged in within the specified date range (include) or those who didn't
            last log in within the range (exclude). **Possible values**: `include`, `exclude`. **Default**: `include`.
          schema:
            type: string
            enum:
              - include
              - exclude
        - name: sort_order
          in: query
          schema:
            type: string
            enum:
              - desc
              - asc
          description: |
            Control the order of returned users. **Possible values**: `desc` (default), `asc`.
        - name: sort_by
          in: query
          schema:
            type: string
            enum:
              - name
              - role
              - status
              - activity
              - created_at
        - name: page
          in: query
          schema:
            type: "integer"
        - name: page_size
          in: query
          schema:
            type: "integer"
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsersResponse"
              examples:
                Users:
                  $ref: "#/components/examples/Users"
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '404':
          $ref: '#/components/responses/404NotFound'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'

    post:
      summary: Create user
      description: Create a new user.
      externalDocs:
        description: Learn more about creating users.
        url: https://cloudinary.com/documentation/provisioning_api#create_user
      operationId: createUser
      tags:
        - Users
      requestBody:
        required: true
        description: User details.
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/UserRequest"
              required:
                - name
                - email
            examples:
              CreateUserExample:
                $ref: "#/components/examples/CreateUserExample"
      responses:
        '200':
          description: User created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
              examples:
                UserResponseExample:
                  $ref: "#/components/examples/UserResponseExample"
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403NotAllowed'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409AlreadyExists'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'

  /v1_1/provisioning/accounts/{account_id}/users/{user_id}:
    parameters:
      - $ref: '#/components/parameters/AccountIdParam'
      - $ref: '#/components/parameters/userId'

    get:
      summary: Get user
      description: Retrieve a specific user.
      externalDocs:
        description: Learn more about retrieving a specific user.
        url: https://cloudinary.com/documentation/provisioning_api#get_user
      operationId: getUser
      tags:
        - Users
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
              examples:
                UserResponseExample:
                  $ref: "#/components/examples/UserResponseExample"
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '404':
          $ref: '#/components/responses/404NotFound'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'

    put:
      summary: Update user
      description: Update the details of a user.
      externalDocs:
        description: Learn more about updating a specific user.
        url: https://cloudinary.com/documentation/provisioning_api#update_user
      operationId: updateUser
      tags:
        - Users
      requestBody:
        required: true
        description: User details to update.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserRequest"
      responses:
        '200':
          description: User updated successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
              examples:
                UserJohn:
                  $ref: "#/components/examples/UserJohn"

        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403NotAllowed'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409AlreadyExists'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'

    delete:
      summary: Delete user
      description: Delete a specific user.
      externalDocs:
        description: Learn more about deleting a specific user.
        url: https://cloudinary.com/documentation/provisioning_api#delete_user
      operationId: deleteUser
      tags:
        - Users
      responses:
        '200':
          description: User deleted successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403NotAllowed'
        '404':
          $ref: '#/components/responses/404NotFound'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'

  /v1_1/provisioning/accounts/{account_id}/users/{user_id}/groups:
    parameters:
      - $ref: '#/components/parameters/AccountIdParam'
      - $ref: '#/components/parameters/userId'

    get:
      summary: Get user groups
      description: Retrieve the groups that a specific user belongs to.
      externalDocs:
        description: Learn more about retrieving user groups.
        url: https://cloudinary.com/documentation/provisioning_api#get_users_groups
      operationId: getGroupsForUser
      tags:
        - Users
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserGroupsListResponse"
              examples:
                UserGroupsList:
                  $ref: "#/components/examples/UserGroupsList"
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '404':
          $ref: '#/components/responses/404NotFound'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'

  /v1_1/provisioning/accounts/{account_id}/users/{user_id}/sub_accounts:
    parameters:
      - $ref: '#/components/parameters/AccountIdParam'
      - $ref: '#/components/parameters/userId'

    get:
      summary: Get user sub-accounts
      description: Retrieve the product environments (sub-accounts) that a specific user has access to.
      externalDocs:
        description: Learn more about retrieving user sub-accounts.
        url: https://cloudinary.com/documentation/provisioning_api#get_user_sub_accounts
      operationId: getSubAccountsForUser
      tags:
        - Users
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserSubAccountsResponse"
              examples:
                UserSubAccounts:
                  $ref: "#/components/examples/UserSubAccounts"
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '404':
          $ref: '#/components/responses/404NotFound'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'

  /v1_1/provisioning/accounts/{account_id}/user_groups:
    parameters:
      - $ref: '#/components/parameters/AccountIdParam'
    get:
      parameters:
        - $ref: '#/components/parameters/userGroupExtendedDetails'
      summary: Get User Groups
      description: Retrieve an array of all user groups in the account.
      externalDocs:
        description: Learn more about retrieving user groups.
        url: https://cloudinary.com/documentation/provisioning_api#get_user_groups
      operationId: getUserGroups
      tags:
        - User Groups
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroupsResponse'
              examples:
                UserGroups:
                  $ref: "#/components/examples/UserGroups"
                UserGroupsExtendedDetails:
                  $ref: "#/components/examples/UserGroupsExtendedDetails"
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '404':
          $ref: '#/components/responses/404NotFound'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'

    post:
      summary: Create User Group
      description: Create a new user group for the account.
      externalDocs:
        description: Learn more about creating user groups.
        url: https://cloudinary.com/documentation/provisioning_api#create_user_group
      operationId: createUserGroup
      tags:
        - User Groups
      requestBody:
        required: true
        description: User group details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserGroupRequest'
      responses:
        '200':
          description: User group created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroup'
              examples:
                UserGroupDesigners:
                  $ref: "#/components/examples/UserGroupDesigners"
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403NotAllowed'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409AlreadyExists'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'

  /v1_1/provisioning/accounts/{account_id}/user_groups/{group_id}:
    parameters:
      - $ref: '#/components/parameters/AccountIdParam'
      - $ref: '#/components/parameters/userGroupId'

    get:
      parameters:
        - $ref: '#/components/parameters/userGroupExtendedDetails'
      summary: Get User Group
      description: Retrieve a specific user group.
      externalDocs:
        description: Learn more about retrieving a specific user group.
        url: https://cloudinary.com/documentation/provisioning_api#get_user_group
      operationId: getUserGroup
      tags:
        - User Groups
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroup'
              examples:
                UserGroupDesigners:
                  $ref: "#/components/examples/UserGroupDesigners"
                UserGroupDesignersExtendedDetails:
                  $ref: "#/components/examples/UserGroupDesignersExtendedDetails"
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '404':
          $ref: '#/components/responses/404NotFound'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'

    put:
      summary: Update User Group
      description: Update the name of a specified user group.
      externalDocs:
        description: Learn more about updating a specific user group.
        url: https://cloudinary.com/documentation/provisioning_api#update_user_group
      operationId: updateUserGroup
      tags:
        - User Groups
      requestBody:
        required: true
        description: User group details to update.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserGroupRequest'
            examples:
              UserGroupDesignersRequest:
                $ref: "#/components/examples/UserGroupDesignersRequest"
      responses:
        '200':
          description: User group updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroup'
              examples:
                UserGroupUpdate:
                  $ref: "#/components/examples/UserGroupUpdate"
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403NotAllowed'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409AlreadyExists'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'

    delete:
      summary: Delete User Group
      description: Delete a user group with the specified ID.
      externalDocs:
        description: Learn more about deleting a specific user group.
        url: https://cloudinary.com/documentation/provisioning_api#delete_user_group
      operationId: deleteUserGroup
      tags:
        - User Groups
      responses:
        '200':
          description: User group deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403NotAllowed'
        '404':
          $ref: '#/components/responses/404NotFound'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'

  /v1_1/provisioning/accounts/{account_id}/user_groups/{group_id}/users:
    parameters:
      - $ref: '#/components/parameters/AccountIdParam'
      - $ref: '#/components/parameters/userGroupId'

    get:
      summary: Get Users in User Group
      description: Retrieve the users in the group with the specified ID.
      externalDocs:
        description: Learn more about retrieving users in a specific user group.
        url: https://cloudinary.com/documentation/provisioning_api#get_user_group_users
      operationId: getUsersInUserGroup
      tags:
        - User Groups
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroupUsersResponse'
              examples:
                UserGroupUsers:
                  $ref: "#/components/examples/UserGroupUsers"
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '404':
          $ref: '#/components/responses/404NotFound'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'


  /v1_1/provisioning/accounts/{account_id}/user_groups/{group_id}/users/{user_id}:
    parameters:
      - $ref: '#/components/parameters/AccountIdParam'
      - $ref: '#/components/parameters/userGroupId'
      - $ref: '#/components/parameters/userId'

    post:
      summary: Add User to User Group
      description: Add a user to a group with the specified ID.
      externalDocs:
        description: Learn more about adding users to a specific user group.
        url: https://cloudinary.com/documentation/provisioning_api#add_user_to_group
      operationId: addUserToUserGroup
      tags:
        - User Groups
      responses:
        '200':
          description: User added to group successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroupUser'
              examples:
                UserGroupUserJohn:
                  $ref: "#/components/examples/UserGroupUserJohn"
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403NotAllowed'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409AlreadyExists'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'

    delete:
      summary: Remove User from User Group
      description: Remove a user from a group with the specified ID.
      externalDocs:
        description: Learn more about removing users from a specific user group.
        url: https://cloudinary.com/documentation/provisioning_api#remove_user_from_group
      operationId: removeUserFromUserGroup
      tags:
        - User Groups
      responses:
        '200':
          description: User removed from group successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroupUsersResponse'
              examples:
                UserGroupUsers:
                  $ref: "#/components/examples/UserGroupUsersNoJohn"
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403NotAllowed'
        '404':
          $ref: '#/components/responses/404NotFound'
        '420':
          $ref: '#/components/responses/420MaxUsageRateExceeded'
        '429':
          $ref: '#/components/responses/429TooManyRequests'

  /v1_1/provisioning/accounts/{account_id}/billing_usage:
    parameters:
      - $ref: '#/components/parameters/AccountIdParam'
    get:
      tags:
        - Billing Usage
      summary: Get billing usage information
      description: |
        Retrieve billing usage metrics for your account and product environments,
        including storage, bandwidth, impressions, and transformations.

        If `year` is provided:
          - **Annual subscription**: Returns the single annual usage cycle that began in the specified year (if any).
          - **Monthly subscription**: Returns all monthly usage cycles that began in the specified year.

        If `year` is not provided:
          - Returns usage for the year in which the current active subscription period began.
          - If no active subscription exists, an empty list is returned.

        **Note**: Usage metrics are updated daily, so calling this endpoint once per day gives you the latest data.
      operationId: getBillingUsage
      parameters:
        - name: year
          in: query
          required: false
          schema:
            type: integer
            format: int32
          description: The year to retrieve billing usage for. Behavior depends on subscription type (see above).
          example: 2024
        - name: include_prodenv_breakdown
          in: query
          required: false
          schema:
            type: boolean
          description: |
            Whether to include usage details by product environment. **Default**: false.
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BillingUsageResponse"
              examples:
                ProPAYG:
                  $ref: "#/components/examples/BillingUsageResponse_ProPAYG"
                AdvancedExtraPAYG:
                  $ref: "#/components/examples/BillingUsageResponse_AdvancedExtraPAYG"
                AdvancedPAYG:
                  $ref: "#/components/examples/BillingUsageResponse_AdvancedPAYG"
                ProPAYGPlus:
                  $ref: "#/components/examples/BillingUsageResponse_ProPAYGPlus"
                MultiPlan:
                  $ref: "#/components/examples/BillingUsageResponse_MultiPlan"
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403NotAllowed'
        '404':
          $ref: '#/components/responses/404NotFound'
        '429':
          $ref: '#/components/responses/429TooManyRequests'

  /v2/accounts/permissions/public/catalog:
    get:
      # --------
      #  Get system roles and policies catalog
      # ------------------------------------
      x-speakeasy-name-override: getCatalog
      x-speakeasy-mcp:
        name: get-catalog
        scopes:
          - admin
        title: Get System Roles and Policies Catalog
        readOnlyHint: true
        idempotentHint: true
      summary: Get system roles and policies catalog
      description: Retrieves the catalog of predefined system roles and their associated policies.
      operationId: getSystemRolesAndPoliciesCatalog
      tags:
        - Public
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemRolesAndPoliciesCatalogResponse'
        '400':
          description: Bad request

  # -----------------------------------------------------------------------
  /v2/accounts/permissions/public/validate:
    post:
      # --------
      #  Validate a Cedar policy
      # ------------------------------------
      x-speakeasy-name-override: validatePolicy
      x-speakeasy-mcp:
        name: validate-policy
        scopes:
          - admin
        title: Validate Cedar Policy
        readOnlyHint: true
        idempotentHint: true
      summary: Validate a Cedar policy
      description: Validate a Cedar policy
      operationId: validateCedarPolicy
      tags:
        - Public
      requestBody:
        description: Cedar policy.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateCedarPolicyRequest'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateCedarPolicyResponse'
              examples:
                ValidateCedarPolicyResponseExample:
                  $ref: '#/components/examples/ValidateCedarPolicyResponseExample'
        '400':
          description: Bad request

  # -----------------------------------------------------------------------
  /v2/accounts/permissions/public/schema:
    get:
      # --------
      #  Get Cedar schema
      # ------------------------------------
      x-speakeasy-name-override: getSchema
      x-speakeasy-mcp:
        name: get-schema
        scopes:
          - admin
        title: Get Cedar Schema
        readOnlyHint: true
        idempotentHint: true
      summary: Get Cedar schema
      description: Get Cedar schema
      operationId: getCedarSchema
      tags:
        - Public
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CedarSchemaResponse'
        '400':
          description: Bad request
  # -----------------------------------------------------------------------
  /v2/accounts/{account_id}/permissions/policies/system:
    parameters:
      - $ref: '#/components/parameters/AccountIdParam'
    get:
      # --------
      #  Get a list of system policies
      # ------------------------------------
      x-speakeasy-group: policies.system
      x-speakeasy-name-override: list
      x-speakeasy-mcp:
        name: list-system-policies
        scopes:
          - admin
        title: List System Policies
        readOnlyHint: true
        idempotentHint: true
      summary: Get system policies
      description: |
        Retrieve all system-defined permission policies. Optionally filter the results by `scope_type` (account or product environment) and/or `permission_type` (global or content-specific).

        **Note:** If `scope_type` isn't specified as `prodenv`, the account-level policies will be returned.
      operationId: getSystemPolicies
      tags:
        - System Policies
      parameters:
        - $ref: '#/components/parameters/PermissionTypeOptionalParam'
        - $ref: '#/components/parameters/ScopeTypeParam'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemPoliciesResponse'
              examples:
                SystemPoliciesExample:
                  $ref: '#/components/examples/SystemPoliciesExample'

        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                AuthorizationErrorExample:
                  $ref: '#/components/examples/AuthorizationErrorExample'
        '403':
          description: Not allowed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                ForbiddenErrorExample:
                  $ref: '#/components/examples/ForbiddenErrorExample'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                InternalServerErrorExample:
                  $ref: '#/components/examples/InternalServerErrorExample'

  # -----------------------------------------------------------------------

  /v2/accounts/{account_id}/permissions/policies/custom:
    parameters:
      - $ref: '#/components/parameters/AccountIdParam'
    get:
      # --------
      #  Get a list of custom policies
      # ------------------------------------
      x-speakeasy-group: policies.custom
      x-speakeasy-name-override: list
      x-speakeasy-mcp:
        name: list-custom-policies
        scopes:
          - admin
        title: List Custom Policies
        readOnlyHint: true
        idempotentHint: true
      summary: Get custom policies
      description: |
        Retrieve all custom permission policies defined for a specific scope. The scope can be at the account level or within a specific product environment.

        **Notes:**
          * If `scope_type` isn't specified as `prodenv`, the account-level policies will be returned.

          * If `scope_type` is specified as `prodenv`, `scope_id` is required.
      operationId: getCustomPolicies
      tags:
        - Custom Policies
      parameters:
        - $ref: '#/components/parameters/ScopeTypeParam'
        - $ref: '#/components/parameters/ScopeIdParam'
        - $ref: '#/components/parameters/EnabledParam'
        - $ref: '#/components/parameters/CursorParam'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomPoliciesResponse'
              examples:
                CustomPoliciesExample:
                  $ref: '#/components/examples/CustomPoliciesExample'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/AuthorizationErrorExample'
        '403':
          description: Not allowed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/ForbiddenErrorExample'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                internalServerErrorExample:
                  $ref: '#/components/examples/InternalServerErrorExample'

    post:
      # --------
      #  Create a new custom permission policy
      # ------------------------------------
      x-speakeasy-group: policies.custom
      x-speakeasy-name-override: create
      x-speakeasy-mcp:
        name: create-custom-policy
        scopes:
          - admin
        title: Create Custom Policy
        destructiveHint: false
      summary: Create custom policy
      description: Create a new custom policy with a statement defined in Cedar. This policy specifies permissions for a principal,
        allowing a specific action on a designated resource, within a particular scope.
      operationId: createCustomPolicy
      externalDocs:
        description: Learn more about creating a new custom policy
        url: https://cloudinary.com/documentation/permissions_api_guide#create_a_policy_statement
      tags:
        - Custom Policies
      requestBody:
        description: Policy details.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomPolicy'
            examples:
              createCustomPolicyExample:
                $ref: '#/components/examples/CreateCustomPolicyExample'

      responses:
        '201':
          description: Policy created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomPolicyResponse'
              examples:
                createPolicyResponse:
                  $ref: '#/components/examples/CreateCustomPolicyResponseExample'

        '400':
          description: Missing fields, invalid field, or invalid Cedar statement
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                missingFieldsErrorExample:
                  $ref: '#/components/examples/MissingFieldsErrorExample'
                invalidFieldErrorExample:
                  $ref: '#/components/examples/InvalidFieldErrorExample'
                cedarErrorExample:
                  $ref: '#/components/examples/CedarErrorExample'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/AuthorizationErrorExample'
        '403':
          description: Not allowed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/ForbiddenErrorExample'
        '409':
          description: Already exists for the scope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                customPolicyAlreadyExistsErrorExample:
                  $ref: '#/components/examples/CustomPolicyAlreadyExistsErrorExample'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                internalServerErrorExample:
                  $ref: '#/components/examples/InternalServerErrorExample'

  # -----------------------------------------------------------------------

  /v2/accounts/{account_id}/permissions/policies/custom/{policy_id}:
    parameters:
      - $ref: '#/components/parameters/AccountIdParam'
      - $ref: '#/components/parameters/PolicyIdParam'
    get:
      # --------
      #  Get a specific policy
      # ------------------------------------
      x-speakeasy-group: policies.custom
      x-speakeasy-name-override: get
      x-speakeasy-mcp:
        name: get-custom-policy
        scopes:
          - admin
        title: Get Custom Policy
        readOnlyHint: true
        idempotentHint: true
      summary: Get custom policy
      description: Get a specific custom policy.
      operationId: getCustomPolicy
      tags:
        - Custom Policies
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomPolicyResponse'
              examples:
                CustomPolicyExample:
                  $ref: '#/components/examples/CustomPolicyExample'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/AuthorizationErrorExample'
        '403':
          description: Not allowed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/ForbiddenErrorExample'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                policyNotFoundErrorExample:
                  $ref: '#/components/examples/PolicyNotFoundErrorExample'

    put:
      # --------
      #  Update a specific policy
      # ------------------------------------
      summary: Update custom policy
      x-speakeasy-group: policies.custom
      x-speakeasy-name-override: update
      x-speakeasy-mcp:
        name: update-custom-policy
        scopes:
          - admin
        title: Update Custom Policy
        destructiveHint: false
        idempotentHint: true
      description: |
        Update a specific custom policy by providing the entire policy entity in the request body. Ensure the new `policy_statement` includes modifications. Existing permissions will be replaced with the new data.

        *Note:* Updating a policy with an identical `policy_statement` will trigger a 409 error.

      operationId: updateCustomPolicy
      tags:
        - Custom Policies
      requestBody:
        description: Policy details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomPolicy'
            examples:
              updateCustomPolicyExample:
                $ref: '#/components/examples/UpdateCustomPolicyExample'
      responses:
        '200':
          description: Policy updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomPolicyResponse"
              examples:
                updatePolicyResponse:
                  $ref: '#/components/examples/UpdateCustomPolicyResponseExample'
        '400':
          description: Missing fields, invalid field, or invalid Cedar statement
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                missingFieldsUpdateErrorExample:
                  $ref: '#/components/examples/MissingFieldsErrorExample'
                invalidFieldErrorExample:
                  $ref: '#/components/examples/InvalidFieldErrorExample'
                cedarErrorExample:
                  $ref: '#/components/examples/CedarErrorExample'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/AuthorizationErrorExample'
        '403':
          description: Not allowed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/ForbiddenErrorExample'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                policyNotFoundErrorExample:
                  $ref: '#/components/examples/PolicyNotFoundErrorExample'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                customPolicyAlreadyExistsErrorExample:
                  $ref: '#/components/examples/CustomPolicyAlreadyExistsErrorExample'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                internalServerErrorExample:
                  $ref: '#/components/examples/InternalServerErrorExample'

    delete:
      # --------
      #  Delete a policy
      # ------------------------------------
      x-speakeasy-group: policies.custom
      x-speakeasy-name-override: delete
      x-speakeasy-mcp:
        name: delete-custom-policy
        scopes:
          - admin
        title: Delete Custom Policy
        destructiveHint: true
        idempotentHint: true
      summary: Delete custom policy
      description: Delete a specific custom policy.
      operationId: deleteCustomPolicy
      tags:
        - Custom Policies
      responses:
        '204':
          description: Successful operation
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/AuthorizationErrorExample'
        '403':
          description: Not allowed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/ForbiddenErrorExample'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                policyNotFoundErrorExample:
                  $ref: '#/components/examples/PolicyNotFoundErrorExample'
  # -----------------------------------------------------------------------

  /v2/accounts/{account_id}/permissions/policies/effective:
    parameters:
      - $ref: '#/components/parameters/AccountIdParam'
    get:
      # --------
      #  Get a list of effective policies
      # ------------------------------------
      x-speakeasy-group: policies.effective
      x-speakeasy-name-override: list
      x-speakeasy-mcp:
        name: list-effective-policies
        scopes:
          - admin
        title: List Effective Policies
        readOnlyHint: true
        idempotentHint: true
      summary: Get effective policies
      description: |
        Retrieve all roles (along with their system permission policies) associated with principals, and all custom permission policies directly added to principals, all within a specified scope.

        Optionally specify a principal to only include roles and policies associated with that principal.
      operationId: getEffectivePolicies
      tags:
        - Effective Policies
      parameters:
        - $ref: '#/components/parameters/ScopeTypeParam'
        - $ref: '#/components/parameters/ScopeIdParam'
        - $ref: '#/components/parameters/PrincipalTypeParam'
        - $ref: '#/components/parameters/PrincipalIdParam'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EffectivePoliciesResponse'
              examples:
                EffectivePoliciesExample:
                  $ref: '#/components/examples/EffectivePoliciesExample'
        '400':
          description: Invalid field
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                invalidFieldErrorExample:
                  $ref: '#/components/examples/InvalidFieldErrorExample'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/AuthorizationErrorExample'
        '403':
          description: Not allowed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/ForbiddenErrorExample'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                policyNotFoundErrorExample:
                  $ref: '#/components/examples/ScopeNotFoundErrorExample'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                internalServerErrorExample:
                  $ref: '#/components/examples/InternalServerErrorExample'
  # -----------------------------------------------------------------------
  /v2/accounts/{account_id}/permissions/roles:
    parameters:
      - $ref: '#/components/parameters/AccountIdParam'
    get:
      # --------
      #  Get a list of roles
      # ------------------------------------
      x-speakeasy-name-override: list
      x-speakeasy-mcp:
        name: list-roles
        scopes:
          - admin
        title: List Roles
        readOnlyHint: true
        idempotentHint: true
      summary: Get roles
      description: |
        Retrieve all system and custom roles of a specific `permission_type` (global or content-specific). Optionally filter by `scope_type`, `management_type`, and `policy_parameters`.

      operationId: getRoles
      tags:
        - Roles
      parameters:
        - $ref: '#/components/parameters/ScopeTypeParam'
        - $ref: '#/components/parameters/PermissionTypeParam'
        - $ref: '#/components/parameters/ManagementTypeParam'
        - $ref: '#/components/parameters/PolicyParameterTypesParam'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RolesResponse'
              examples:
                GetRolesExample:
                  $ref: '#/components/examples/GetRolesExample'

        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionsErrorResponse'
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/AuthorizationErrorExample'
        '403':
          description: Not allowed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/ForbiddenErrorExample'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionsErrorResponse'
              examples:
                internalServerErrorExample:
                  $ref: '#/components/examples/InternalServerErrorExample'

    post:
      # --------
      #  Create a new role
      # ------------------------------------
      x-speakeasy-name-override: create
      x-speakeasy-mcp:
        name: create-role
        scopes:
          - admin
        title: Create Role
        destructiveHint: false
      summary: Create custom role
      description: Create a new custom role.
      operationId: createRole
      tags:
        - Roles
      requestBody:
        description: Role details.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRole'
            examples:
              createGlobalRoleExample:
                $ref: '#/components/examples/CreateGlobalRoleExample'
              createContentRoleExample:
                $ref: '#/components/examples/CreateContentRoleExample'
              createAcctRoleExample:
                $ref: '#/components/examples/CreateAcctRoleExample'

      responses:
        '201':
          description: Role created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleResponse'
              examples:
                createGlobalRoleResponseExample:
                  $ref: '#/components/examples/CreateGlobalRoleResponseExample'
                createContentRoleResponseExample:
                  $ref: '#/components/examples/CreateContentRoleResponseExample'
                createAcctRoleResponseExample:
                  $ref: '#/components/examples/CreateAcctRoleResponseExample'

        '400':
          description: Missing fields or invalid field
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                missingFieldsErrorExample:
                  $ref: '#/components/examples/MissingFieldsErrorExample'
                invalidFieldErrorExample:
                  $ref: '#/components/examples/InvalidFieldErrorExample'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/AuthorizationErrorExample'
        '403':
          description: Not allowed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/ForbiddenErrorExample'
        '409':
          description: Already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                roleAlreadyExistsErrorExample:
                  $ref: '#/components/examples/RoleAlreadyExistsErrorExample'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                internalServerErrorExample:
                  $ref: '#/components/examples/InternalServerErrorExample'

  # -----------------------------------------------------------------------

  /v2/accounts/{account_id}/permissions/roles/{role_id}:
    parameters:
      - $ref: '#/components/parameters/AccountIdParam'
      - $ref: '#/components/parameters/RoleIdParam'
    get:
      # --------
      #  Get a specific role
      # ------------------------------------
      x-speakeasy-name-override: get
      x-speakeasy-mcp:
        name: get-role
        scopes:
          - admin
        title: Get Role
        readOnlyHint: true
        idempotentHint: true
      summary: Get role
      description: Get a specific system or custom role.
      operationId: getRole
      tags:
        - Roles
      parameters:
        - $ref: '#/components/parameters/FolderId'
        - $ref: '#/components/parameters/AssetId'
        - $ref: '#/components/parameters/CollectionId'
        - $ref: '#/components/parameters/PolicyParameterKeyParam'
        - $ref: '#/components/parameters/PolicyParameterValueParam'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleResponse'
              examples:
                GetRoleExample:
                  $ref: '#/components/examples/GetRoleExample'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/AuthorizationErrorExample'
        '403':
          description: Not allowed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/ForbiddenErrorExample'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                roleNotFoundErrorExample:
                  $ref: '#/components/examples/RoleNotFoundErrorExample'

    put:
      # --------
      #  Update a specific role
      # ------------------------------------
      summary: Update custom role
      x-speakeasy-name-override: update
      x-speakeasy-mcp:
        name: update-role
        scopes:
          - admin
        title: Update Role
        destructiveHint: false
        idempotentHint: true
      description: |
        Update a specific custom role by providing all relevant details, including those you want to keep as-is.

        *Note:* Updating a role with a name that already exists will trigger a 409 error.

      operationId: updateRole
      tags:
        - Roles
      requestBody:
        description: Role details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRole'
            examples:
              updateRoleExample:
                $ref: '#/components/examples/UpdateRoleExample'
      responses:
        '200':
          description: Role updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RoleResponse"
              examples:
                updatePolicyResponse:
                  $ref: '#/components/examples/UpdateRoleResponseExample'
        '400':
          description: Missing fields, invalid field
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                missingFieldsErrorExample:
                  $ref: '#/components/examples/MissingFieldsErrorExample'
                invalidPolicyIDFieldErrorExample:
                  $ref: '#/components/examples/InvalidPolicyIDFieldErrorExample'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/AuthorizationErrorExample'
        '403':
          description: Not allowed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/ForbiddenErrorExample'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                roleNotFoundErrorExample:
                  $ref: '#/components/examples/RoleNotFoundErrorExample'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                roleAlreadyExistsErrorExample:
                  $ref: '#/components/examples/RoleAlreadyExistsErrorExample'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                internalServerErrorExample:
                  $ref: '#/components/examples/InternalServerErrorExample'

    delete:
      # --------
      #  Delete a role
      # ------------------------------------
      x-speakeasy-name-override: delete
      x-speakeasy-mcp:
        name: delete-role
        scopes:
          - admin
        title: Delete Role
        destructiveHint: true
        idempotentHint: true
      summary: Delete custom role
      description: Delete a specific custom role.
      operationId: deleteRole
      tags:
        - Roles
      parameters:
        - $ref: '#/components/parameters/ForceDeleteParam'
      responses:
        '204':
          description: Successful operation
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/AuthorizationErrorExample'
        '403':
          description: Not allowed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/ForbiddenErrorExample'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                roleNotFoundErrorExample:
                  $ref: '#/components/examples/RoleNotFoundErrorExample'

  # -----------------------------------------------------------------------
  /v2/accounts/{account_id}/permissions/principal_roles:
    parameters:
      - $ref: '#/components/parameters/AccountIdParam'
    get:
      # --------
      #  Get all roles for a principal
      # ------------------------------------
      x-speakeasy-name-override: listRoles
      x-speakeasy-mcp:
        name: list-principal-roles
        scopes:
          - admin
        title: List Principal's Roles
        readOnlyHint: true
        idempotentHint: true
      summary: Get a principal's roles
      description: Retrieve all roles associated with a specific principal.
      operationId: getPrincipalRoles
      tags:
        - Principals
      parameters:
        - $ref: '#/components/parameters/PrincipalTypeRequiredParam'
        - $ref: '#/components/parameters/PrincipalIdRequiredParam'
        - $ref: '#/components/parameters/PermissionTypeParam'
        - $ref: '#/components/parameters/ManagementTypeParam'
        - $ref: '#/components/parameters/ScopeTypeParam'
        - $ref: '#/components/parameters/ScopeIdParam'
        - $ref: '#/components/parameters/FolderId'
        - $ref: '#/components/parameters/AssetId'
        - $ref: '#/components/parameters/CollectionId'
        - $ref: '#/components/parameters/PolicyParameterKeyParam'
        - $ref: '#/components/parameters/PolicyParameterValueParam'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrincipalRolesResponse'
              examples:
                GetPrincipalRolesExample:
                  $ref: '#/components/examples/GetPrincipalRolesExample'
                GetPrincipalRolesWithParamKeyValueExample:
                  $ref: '#/components/examples/GetPrincipalRolesWithParamKeyValueExample'
        '400':
          description: Missing fields, invalid fields
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                missingPrincipalFieldsErrorExample:
                  $ref: '#/components/examples/MissingPrincipalFieldsErrorExample'
                invalidFieldErrorExample:
                  $ref: '#/components/examples/InvalidFieldErrorExample'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionsErrorResponse'
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/AuthorizationErrorExample'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                principalNotFoundErrorExample:
                  $ref: '#/components/examples/PrincipalNotFoundErrorExample'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionsErrorResponse'
              examples:
                internalServerErrorExample:
                  $ref: '#/components/examples/InternalServerErrorExample'
    put:
      # --------
      #  Add/Remove roles to a principal
      # ------------------------------------
      x-speakeasy-name-override: updateRoles
      x-speakeasy-mcp:
        name: update-principal-roles
        scopes:
          - admin
        title: Update Principal's Roles
        destructiveHint: false
      summary: Assign roles to a principal
      description: Add or remove roles associated with a principal.
      operationId: updatePrincipalRoles
      tags:
        - Principals
      requestBody:
        description: Principal and roles details.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePrincipalRolesRequest'
      responses:
        '200':
          description: Successful operation

        '400':
          description: Missing fields, invalid fields
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                missingPrincipalFieldsErrorExample:
                  $ref: '#/components/examples/MissingPrincipalFieldsErrorExample'
                InvalidOperationFieldErrorExample:
                  $ref: '#/components/examples/InvalidOperationFieldErrorExample'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/AuthorizationErrorExample'
        '403':
          description: Not allowed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/ForbiddenErrorExample'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"

  # -----------------------------------------------------------------------
  /v2/accounts/{account_id}/permissions/principal_roles/inspect:
    parameters:
      - $ref: '#/components/parameters/AccountIdParam'
    get:
      # --------
      #  Inspect
      # ------------------------------------
      summary: Inspect
      x-speakeasy-mcp:
        name: inspect-principals
        scopes:
          - admin
        title: Inspect Principals
        readOnlyHint: true
        idempotentHint: true
      description: |
        Retrieves principals and their assigned roles within a specified scope, based on query filters.

        Use this endpoint to determine which users, groups, API keys, or account API keys have roles applied at:
        * A specific `scope_type` ("account" or "prodenv")
        * A specific `scope_id` (for product environments)
        * Optional content filters (such as `folder_id`, `collection_id`, or `param_key` / `param_value`)
        * Optional `principal_type` (and `principal_id`)

        The response includes all principals that match the specified filters, along with the roles applied to them within that context.

        This endpoint is useful when you want to:
        * Audit who has access within a given scope
        * Identify all principals assigned to roles for a specific folder, collection, asset, or product environment
        * Retrieve role assignments dynamically based on filtering criteria
      operationId: inspect
      tags:
        - Principals
      parameters:
        - $ref: '#/components/parameters/ScopeTypeRequiredParam'
        - $ref: '#/components/parameters/ScopeIdParam'
        - $ref: '#/components/parameters/PrincipalTypeParam'
        - $ref: '#/components/parameters/PrincipalIdParam'
        - $ref: '#/components/parameters/FolderId'
        - $ref: '#/components/parameters/AssetId'
        - $ref: '#/components/parameters/CollectionId'
        - $ref: '#/components/parameters/PolicyParameterKeyParam'
        - $ref: '#/components/parameters/PolicyParameterValueParam'
        - $ref: '#/components/parameters/CursorParam'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrincipalRolesInspectResponse'
              examples:
                InspectExampleFolder:
                  $ref: '#/components/examples/InspectExampleFolder'
                InspectExampleAllFolders:
                  $ref: '#/components/examples/InspectExampleAllFolders'
                InspectExampleProdEnv:
                  $ref: '#/components/examples/InspectExampleProdEnv'
        '400':
          description: Missing fields, invalid fields
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionsErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionsErrorResponse'
    post:
      # --------
      #  Inspect multiple
      # ------------------------------------
      x-speakeasy-mcp:
        name: inspect-principals-multiple
        scopes:
          - admin
        title: Inspect Multiple Principals
        readOnlyHint: true
        idempotentHint: true
      summary: Inspect multiple
      description: |
        Retrieves role assignments for a specified list of principals within a shared scope and optional policy parameters.

        Use this endpoint when you already know which principals you want to evaluate and want to check their role assignments in a single request.

        In this request:
        * You explicitly provide the `principals` array in the request body.
        * All principals are evaluated against the same `scope_type`, optional `scope_id`, and optional `policy_parameters`.
        * Unlike `Inspect`, this endpoint doesn't search for matching principals. It evaluates only the principals you provide.

        This endpoint is useful for:
        * Verify role assignments for multiple specified principals at once
        * Comparing role assignments across specific users, groups, or keys
        * Reducing multiple per-principal `Inspect` calls into a single request
      operationId: inspectMultiple
      tags:
        - Principals
      requestBody:
        description: Role assignments for multiple principals.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InspectRequest'
            examples:
              InspectMultipleRequestExample:
                $ref: '#/components/examples/InspectMultipleRequestExample'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrincipalRolesInspectResponse'
              examples:
                InspectMultipleResponseExample:
                  $ref: '#/components/examples/InspectMultipleResponseExample'
        '400':
          description: Missing fields, invalid fields
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionsErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionsErrorResponse'
  # -----------------------------------------------------------------------
  /v2/accounts/{account_id}/permissions/roles/{role_id}/principals:
    parameters:
      - $ref: '#/components/parameters/AccountIdParam'
      - $ref: '#/components/parameters/RoleIdParam'
    get:
      # --------
      #  Get all principals for a role
      # ------------------------------------
      x-speakeasy-name-override: listPrincipals
      x-speakeasy-mcp:
        name: list-role-principals
        scopes:
          - admin
        title: List Role's Principals
        readOnlyHint: true
        idempotentHint: true
      summary: Get a role's principals
      description: Retrieve all principals associated with a specific role.
      operationId: getRolePrincipals
      tags:
        - Roles
      parameters:
        - $ref: '#/components/parameters/ScopeTypeParam'
        - $ref: '#/components/parameters/ScopeIdParam'
        - $ref: '#/components/parameters/VerboseParam'
        - $ref: '#/components/parameters/FolderId'
        - $ref: '#/components/parameters/AssetId'
        - $ref: '#/components/parameters/CollectionId'
        - $ref: '#/components/parameters/PolicyParameterKeyParam'
        - $ref: '#/components/parameters/PolicyParameterValueParam'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrincipalsResponse'
              examples:
                GetRolePrincipalsExample:
                  $ref: '#/components/examples/GetRolePrincipalsExample'
                GetRolePrincipalsWithParamKeyValueExample:
                  $ref: '#/components/examples/GetRolePrincipalsWithParamKeyValueExample'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/AuthorizationErrorExample'
        '403':
          description: Not allowed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/ForbiddenErrorExample'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                roleNotFoundErrorExample:
                  $ref: '#/components/examples/RoleNotFoundErrorExample'
    put:
      # --------
      #  Add/Remove principals associated with a role
      # ------------------------------------
      x-speakeasy-name-override: updatePrincipals
      x-speakeasy-mcp:
        name: update-role-principals
        scopes:
          - admin
        title: Update Role's Principals
        destructiveHint: false
      summary: Assign principals to a role
      description: Add or remove principals associated with a role.
      operationId: updateRolePrincipals
      tags:
        - Roles
      requestBody:
        description: Principals details.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRolePrincipalsRequest'
      responses:
        '200':
          description: Successful operation
        '400':
          description: Missing fields, invalid fields
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                missingFieldsErrorExample:
                  $ref: '#/components/examples/MissingRoleFieldsErrorExample'
                invalidOperationFieldErrorExample:
                  $ref: '#/components/examples/InvalidOperationFieldErrorExample'
        '401':
          description: Authorization required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/AuthorizationErrorExample'
        '403':
          description: Not allowed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                authorizationErrorExample:
                  $ref: '#/components/examples/ForbiddenErrorExample'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionsErrorResponse"
              examples:
                roleNotFoundErrorExample:
                  $ref: '#/components/examples/RoleNotFoundErrorExample'

# -----------------------------------------------------------------------

components:
  schemas:
    ProductEnvironmentRequest:
      type: object
      properties:
        name:
          type: string
          description: The display name for the product environment.
          example: Product3 Application
        cloud_name:
          type: string
          description: The Cloudinary cloud name (optional, default is auto-generated).
          example: product3
        base_sub_account_id:
          type: string
          description: The ID of another product environment to copy settings from (optional).
          example: 0aaaaa1bbbbb2ccccc3ddddd4eeeee5f
        custom_attributes:
          type: object
          description: Custom attributes associated with the product environment (optional).
      required:
        - name

    ProductEnvironmentUpdateRequest:
      type: object
      properties:
        name:
          type: string
          description: The display name for the product environment.
          example: Product3 Application
        cloud_name:
          type: string
          description: |
            The Cloudinary cloud name. An error is returned if the requested name already exists.
            **Note**: Can only be changed for accounts with fewer than 1000 images.
          example: product3
        custom_attributes:
          type: object
          description: Custom attributes associated with the product environment.
        enabled:
          type: boolean
          description: |
            Whether the product environment is enabled. **Default**: true.

    ProductEnvironmentsResponse:
      type: object
      properties:
        sub_accounts:
          type: array
          items:
            $ref: "#/components/schemas/ProductEnvironment"

    ProductEnvironment:
      description: Product Environment
      type: object
      properties:
        cloud_name:
          type: string
        name:
          type: string
          description: The cloud name of the product environment.
        enabled:
          type: boolean
          description: Whether the product environment is enabled or disabled.
        id:
          type: string
          description: The ID of the product environment.
        api_access_keys:
          type: array
          description: The list of the product environment's access keys.
          items:
            $ref: "#/components/schemas/ApiAccessKey"
        created_at:
          type: string
          format: date-time
          description: The date when the product environment was created.
        updated_at:
          type: string
          format: date-time
          description: The date when the product environment was last updated.

    AccessKeyRequest:
      type: object
      properties:
        name:
          type: string
          description: The name of the access key.
          example: "main_key"
        enabled:
          type: boolean
          description: Whether the access key is enabled or disabled.
          example: true

    AccessKeyUpdateRequest:
      type: object
      properties:
        name:
          type: string
          description: The name of the access key.
          example: "main_key"
        enabled:
          type: boolean
          description: Whether the access key is enabled or disabled.
          example: true
        dedicated_for:
          type: string
          enum:
            - webhooks
          description: |
            Designates the access key for a specific purpose while allowing it to be used for other purposes, as well.
            This action replaces any previously assigned key. **Possible values**: `webhooks`
          example: "webhooks"

    AccessKeysResponse:
      type: object
      properties:
        access_keys:
          type: array
          description: The list of the access keys.
          items:
            $ref: "#/components/schemas/AccessKey"
        total:
          type: integer
          description: Total number of the access keys.

    AccessKey:
      type: object
      properties:
        name:
          type: string
          description: The name of the access key.
        api_key:
          type: string
          description: The API key.
        api_secret:
          type: string
          format: password
          description: The API secret.
        created_at:
          type: string
          format: date-time
          description: The date when the access key was created.
        updated_at:
          type: string
          format: date-time
          description: The date when the access key was last updated.
        enabled:
          type: boolean
          description: Whether the access key is enabled or disabled.

    ApiAccessKey:
      description: Brief details of a single API Access Key.
      type: object
      properties:
        key:
          type: string
          description: The API key.
        secret:
          type: string
          format: password
          description: The API secret.
        enabled:
          type: boolean
          description: Whether the access key is enabled or disabled.

    UserRequest:
      type: object
      properties:
        name:
          type: string
          description: The user's name.
          example: John
        email:
          type: string
          description: A unique email address, which serves as the login name and notification address.
          example: john@example.com
        role:
          type: string
          description: The role to assign.
          enum:
            - master_admin
            - admin
            - billing
            - technical_admin
            - reports
            - media_library_admin
            - media_library_user
          example: technical_admin
        sub_account_ids:
          type: array
          description: |
            A list of product environment IDs that this user can access. Ignored if the role is `master_admin`.
            **Default**: all product environments.
          items:
            type: string
        enabled:
          type: boolean
          description: |
            Whether the user is enabled. **Default**: true.
          example: true

    UsersResponse:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: "#/components/schemas/User"

    User:
      description: User details.
      type: object
      properties:
        id:
          type: string
          description: The user's ID.
        name:
          type: string
          description: The user's name.
        first_name:
          type: string
          description: The user's first name.
        last_name:
          type: string
          description: The user's last name.
        role:
          type: string
          description: The user's role.
        email:
          type: string
          format: email
          description: The user's email.
        pending:
          type: boolean
          description: Whether the user is pending.
        enabled:
          type: boolean
          description: Whether the user is enabled.
        created_at:
          type: string
          format: date-time
          description: The date when the user was created.
        updated_at:
          type: string
          format: date-time
          description: The date when the user was last updated.
        last_login:
          type: string
          format: date-time
          description: The date when the user was last logged in.
        all_sub_accounts:
          type: boolean
        providers:
          type: array
          items:
            type: string
          description: The list of authentication providers for the user.
        email_preferences:
          type: object
          description: The user's email preferences.
        account_id:
          type: string
          description: The account ID.
        two_factor:
          type: boolean
          description: Whether two-factor authentication is enabled.
        status:
          type: string
          description: The user's status.
        root:
          type: boolean
          description: Whether the user is a root user.
        technical_role:
          type: string
          description: The user's technical role.
        group_count:
          type: integer
          description: The number of groups the user belongs to.
        sub_account_count:
          type: integer
          description: The number of sub-accounts the user has access to.

    UserGroupRequest:
      type: object
      properties:
        name:
          description: The user group's name.
          type: string
          example: Designers
        extended_details:
          type: boolean
          description: |
            Whether to only return extended (true) or basic information about the group (false).
            **Default**: false.
          example: false

    UserGroupsResponse:
      type: object
      properties:
        user_groups:
          description: A list of user groups.
          type: array
          items:
            $ref: '#/components/schemas/UserGroup'

    UserGroupsListResponse:
      type: object
      properties:
        groups:
          description: A list of user groups that the user belongs to.
          type: array
          items:
            $ref: '#/components/schemas/UserGroupSummary'

    UserSubAccountsResponse:
      type: object
      properties:
        sub_accounts:
          description: A list of product environments (sub-accounts) that the user has access to.
          type: array
          items:
            $ref: '#/components/schemas/SubAccountSummary'

    UserGroupUsersResponse:
      type: object
      properties:
        users:
          description: A list of user group users.
          type: array
          items:
            $ref: '#/components/schemas/UserGroupUser'

    UserGroupSummary:
      description: User group summary.
      type: object
      properties:
        id:
          type: string
          description: The user group's ID.
        name:
          type: string
          description: The user group's name.

    SubAccountSummary:
      description: Product environment (sub-account) summary.
      type: object
      properties:
        id:
          type: string
          description: The product environment's ID.
        name:
          type: string
          description: The product environment's name.
        description:
          type: string
          description: The product environment's description.
        cloud_name:
          type: string
          description: The Cloudinary cloud name of the product environment.
        enabled:
          type: boolean
          description: Whether the product environment is enabled.

    UserGroup:
      description: User group.
      type: object
      properties:
        id:
          type: string
          description: The user group's ID.
        name:
          type: string
          description: The user group's name.
        users:
          type: array
          description: |
            A list of user group users.
            Only returned in extended_details.
          items:
            $ref: '#/components/schemas/UserGroupUser'
        created_at:
          type: string
          format: date-time
          description: |
            The date when the user group was created.
            Only returned in extended_details.
        updated_at:
          type: string
          format: date-time
          description: |
            The date when the user group was last updated.
            Only returned in extended_details.

    UserGroupUser:
      type: object
      description: User group user.
      properties:
        id:
          type: string
          description: The user's ID.
        name:
          type: string
          description: The user's name.
        email:
          type: string
          format: email
          description: The user's email.

    SuccessResponse:
      type: object
      properties:
        message:
          type: string
          example: "ok"

    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: "error"

    BillingUsageResponse:
      type: array
      items:
        type: object
        properties:
          plan_name:
            type: string
            description: The name of the plan (e.g., "Pro PAYG", "Advanced PAYG").
          metric_usage:
            type: array
            items:
              type: object
              properties:
                metric:
                  type: string
                  description: The type of metric being measured (e.g., "credit").
                limit:
                  type: number
                  description: The limit for this metric in the plan.
                cycles:
                  type: array
                  description: Full usage details per billing cycle (monthly or annual, depending on plan).
                  items:
                    type: object
                    properties:
                      from_day:
                        type: string
                        format: date
                        description: The start date of the billing cycle.
                        example: "2024-08-21"
                      to_day:
                        type: string
                        format: date
                        description: The end date of the billing cycle.
                        example: "2024-09-20"
                      usage:
                        type: number
                        description: Total usage for this cycle.
                        example: 25641.55
                      breakdown:
                        type: object
                        description: Usage breakdown by asset type and operation.
                        properties:
                          storage_image:
                            type: number
                            description: Storage usage for images.
                          storage_video:
                            type: number
                            description: Storage usage for videos.
                          storage_raw:
                            type: number
                            description: Storage usage for raw files.
                          transformations_image:
                            type: number
                            description: Transformation usage for images.
                          transformations_video:
                            type: number
                            description: Transformation usage for videos.
                          bandwidth_image:
                            type: number
                            description: Bandwidth usage for images.
                          bandwidth_video:
                            type: number
                            description: Bandwidth usage for videos.
                          bandwidth_raw:
                            type: number
                            description: Bandwidth usage for raw files.
                          image_impressions:
                            type: number
                            description: Number of times images were delivered (impressions).
                          video_seconds:
                            type: number
                            description: Video delivery usage measured in billing seconds (actual viewed duration multiplied
                              by a resolution-based ratio).
                        additionalProperties: false
                      product_environment_breakdown:
                        type: array
                        description: Optional breakdown by product environment. May not be present in all responses.
                        items:
                          $ref: '#/components/schemas/CloudAssetTypeBreakdown'
                monthly_cycles:
                  type: array
                  description: Monthly-level breakdown within a single annual cycle.
                  items:
                    type: object
                    properties:
                      from_day:
                        type: string
                        format: date
                        description: The start date of the monthly billing cycle.
                      to_day:
                        type: string
                        format: date
                        description: The end date of the monthly billing cycle.
                      usage:
                        type: number
                        description: Total usage for this monthly cycle.
                      breakdown:
                        type: object
                        description: Usage breakdown by asset type and operation for the monthly cycle.
                        properties:
                          storage_image:
                            type: number
                            description: Storage usage for images.
                          storage_video:
                            type: number
                            description: Storage usage for videos.
                          storage_raw:
                            type: number
                            description: Storage usage for raw files.
                          transformations_image:
                            type: number
                            description: Transformation usage for images.
                          transformations_video:
                            type: number
                            description: Transformation usage for videos.
                          bandwidth_image:
                            type: number
                            description: Bandwidth usage for images.
                          bandwidth_video:
                            type: number
                            description: Bandwidth usage for videos.
                          bandwidth_raw:
                            type: number
                            description: Bandwidth usage for raw files.
                          image_impressions:
                            type: number
                            description: Number of times images were delivered (impressions).
                          video_seconds:
                            type: number
                            description: Video delivery usage measured in billing seconds (actual viewed duration multiplied
                              by a resolution-based ratio).
                        additionalProperties: false
                      product_environment_breakdown:
                        type: array
                        description: Optional breakdown by product environment for the monthly cycle. May not be present in
                          all responses.
                        items:
                          $ref: '#/components/schemas/CloudAssetTypeBreakdown'

    CloudAssetTypeBreakdown:
      type: object
      properties:
        storage_image:
          type: number
          description: Storage usage for images in this product environment.
        storage_video:
          type: number
          description: Storage usage for videos in this product environment.
        storage_raw:
          type: number
          description: Storage usage for raw files in this product environment.
        transformations_image:
          type: number
          description: Transformation usage for images in this product environment.
        transformations_video:
          type: number
          description: Transformation usage for videos in this product environment.
        bandwidth_image:
          type: number
          description: Bandwidth usage for images in this product environment.
        bandwidth_video:
          type: number
          description: Bandwidth usage for videos in this product environment.
        bandwidth_raw:
          type: number
          description: Bandwidth usage for raw files in this product environment.
        image_impressions:
          type: number
          description: Number of times images were delivered (impressions) in this product environment.
        video_seconds:
          type: number
          description: Video delivery usage measured in billing seconds (actual viewed duration multiplied by a resolution-based
            ratio).
        cloud_name:
          type: string
          description: The name of the product environment.

    ScopeTypeEnum:
      type: string
      description: Specifies where the role/policy is applied, either at the account level or within product environments.
      enum:
        - account
        - prodenv
      example: prodenv
    # ------------------------------------
    PrincipalTypeEnum:
      type: string
      description: The type of principal.
      enum:
        - user
        - group
        - apiKey
        - provisioningKey
      example: user
    # ------------------------------------
    PermissionTypeEnum:
      type: string
      description: Specifies whether permissions apply globally or to specific content.
      enum:
        - global
        - content
      example: global
    # ------------------------------------
    ManagementTypeEnum:
      type: string
      description: Specifies whether the role's policies are managed by Cloudinary (`system`) or by the user (`custom`).
      enum:
        - system
        - custom
      example: system
    # ------------------------------------
    OperationEnum:
      type: string
      description: Specifies the operation to perform. Use `add` to associate or `remove` to disassociate.
      enum:
        - add
        - remove
      example: add
    # ------------------------------------
    ValidateCedarPolicyRequest:
      type: object
      required:
        - policy
      properties:
        policy:
          type: string
          description: The Cedar policy statement to validate.
          example: "permit(principal == Cloudinary::APIKy::\"1234\", action == Cloudinary::Action::\"read\", resource is Cloudinary::Folder
            ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;"
    # ------------------------------------
    UpdateRolePrincipalsRequest:
      type: object
      properties:
        operation:
          $ref: '#/components/schemas/OperationEnum'
        principals:
          type: array
          items:
            $ref: '#/components/schemas/UpdateRolePrincipal'
    # ------------------------------------
    CustomPolicy:
      type: object
      required:
        - scope_type
        - policy_statement
        - name
      properties:
        policy_statement:
          description: A Cedar statement that permits or forbids a principal to perform an action on a resource. Refer to
            the [Permissions API guide](permissions_api_guide) for more information.

          type: string
          example: |
            permit(principal == Cloudinary::APIKey::\"1234\",action==Cloudinary::Action::\"read\",resource is Cloudinary::Folder ) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")} ;
        description:
          description: A short description of the policy.
          nullable: true
          type: string
          example: "Permit read access to the Clothing folder with external ID asdfjkl12347890."
        scope_type:
          $ref: '#/components/schemas/ScopeTypeEnum'
        scope_id:
          description: >
            The ID of a specific product environment, or "all" product environments, where the policy is applied. Required
            and only relevant if scope_type is "prodenv".

            - <product_environment_id>

            - all

            *Note:* The "all" specification is relevant only when creating or updating a policy.
          type: string
          nullable: true
          example: "975l29lz02jt0836fhwi"
        name:
          description: The name assigned to the policy.
          type: string
          example: "Read access to Clothing folder"
        enabled:
          description: Indicates whether the policy is currently active. Can be "true" (enabled) or "false" (disabled).
          type: boolean
          nullable: true
          example: true
          default: true

    # ------------------------------------
    SystemRolesAndPoliciesCatalogResponse:
      type: object
      required:
        - catalog
      properties:
        catalog:
          type: object
          example:
            system_policies:
              - id: "cld::policy::global::ml::access"
                name: "Access the Media Library"
                description: "Access the Media Library within the Console. Without this permission, users can't view any assets."
                category: "Management"
                sub_category: "General operations"
                permission_type: "global"
                scope_type: "prodenv"
                policy: "permit(principal, action, resource == Cloudinary::Feature::\"cld::global::ml::access\");"
              - id: "cld::policy::content::folder::view_download"
                name: "View assets"
                description: "View all assets in the folder and its nested subfolders."
                category: "Folder"
                sub_category: "View and download"
                permission_type: "content"
                scope_type: "prodenv"
                policy: "permit(principal, action == Cloudinary::Action::\"read\", resource is Cloudinary::Asset) when { resource.ancestor_ids.contains(\"\
                  <folder_id>\") };"
            system_roles:
              - id: "cld::role::prodenv::master_admin"
                name: "Master Admin"
                description: "Fully manage product environment, including settings, product features, dashboards, and reports."
                permission_type: "global"
                scope_type: "prodenv"
                system_policy_ids:
                  - "cld::policy::global::ml::access"
                  - "cld::policy::global::folder_and_asset_management::view"
                  - "cld::policy::global::api_keys::manage"
              - id: "cld::role::folder::viewer"
                name: "Viewer"
                description: "View and download public assets."
                permission_type: "content"
                scope_type: "prodenv"
                system_policy_ids:
                  - "cld::policy::content::folder::view_download"
                  - "cld::policy::content::folder::download_public_assets"
    # ------------------------------------
    CedarSchemaResponse:
      type: object
      required:
        - schema
      properties:
        schema:
          type: object
          example:
            Cloudinary:
              actions:
                create:
                  appliesTo:
                    principalTypes: ["APIKey", "User", "Group"]
                    resourceTypes: ["Folder", "Asset", "Collection"]
                read:
                  appliesTo:
                    principalTypes: ["APIKey", "User", "Group"]
                    resourceTypes: ["Folder", "Asset", "Feature"]
                move:
                  appliesTo:
                    principalTypes: ["APIKey", "User", "Group"]
                    resourceTypes: ["Asset", "Folder"]
                    context:
                      type: "Record"
                      attributes:
                        direction:
                          type: "String"
                          required: false
              entityTypes:
                User:
                  shape:
                    type: "Record"
                    attributes:
                      root:
                        type: "Boolean"
                        required: false
                Asset:
                  shape:
                    type: "Record"
                    attributes:
                      ancestor_ids:
                        type: "Set"
                        element:
                          type: "String"
                        required: true
                      resource_type:
                        type: "String"
                        required: true
                Folder:
                  shape:
                    type: "Record"
                    attributes:
                      ancestor_ids:
                        type: "Set"
                        element:
                          type: "String"
                        required: true
                      name:
                        type: "String"
                        required: true
            MediaFlows:
              actions:
                read:
                  appliesTo:
                    principalTypes: ["Cloudinary::User", "Cloudinary::Group"]
                    resourceTypes: ["EasyFlow", "PowerFlow", "LogEntry"]
              entityTypes:
                EasyFlow: {}
                PowerFlow: {}
                LogEntry: {}
    ValidateCedarPolicyResponse:
      type: object
      required:
        - valid
      properties:
        valid:
          type: boolean
          example: false
        errors:
          type: array
          items:
            $ref: "#/components/schemas/CedarError"
    # ------------------------------------
    CedarError:
      type: object
      required:
        - cedar_message
        - cedar_code
      properties:
        cedar_message:
          type: string
        cedar_code:
          type: string
    # ------------------------------------
    CreateCustomPolicy:
      allOf:
        - $ref: '#/components/schemas/CustomPolicy'
    # ------------------------------------
    UpdateCustomPolicy:
      required:
        - enabled
      allOf:
        - $ref: '#/components/schemas/CustomPolicy'
    # ------------------------------------
    CustomPolicyResponse:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/CustomPolicyResponseData"
    # ------------------------------------
    CustomPolicyResponseData:
      type: object
      required:
        - id
        - enabled
        - policy_statement
        - created_at
        - updated_at
        - scope_type
        - name
      properties:
        id:
          description: The unique identifier of the policy.
          type: string
          example: "12jf789l12hwiuencl7aaqey"
        policy_statement:
          description: A Cedar policy that permits or forbids a certain action on a certain element to a principal (user,
            group, or API key).
          type: string
          example: permit(principal == Cloudinary::APIKey::"1234",action==Cloudinary::Action::"read",resource is Cloudinary::Folder
            ) when {resource.ancestor_ids.contains("asdfjkl12347890")} ;
        description:
          description: A short description of the policy.
          type: string
          nullable: true
          example: "Permit read access to the Clothing folder with external ID asdfjkl12347890."
        scope_type:
          $ref: '#/components/schemas/ScopeTypeEnum'
        scope_id:
          description: Returned only if the scope type is product environment. Can be "all" to represent all product environments
            or an ID of a specific product environment.
          type: string
          nullable: true
          example: "975l29lz02jt0836fhwi"
        name:
          description: The name of the policy
          type: string
          example: "Read access to Clothing folder"
        enabled:
          description: Whether the policy is enabled or not
          type: boolean
          example: true
        created_at:
          description: Creation time of the policy in epoch time.
          type: integer
          format: int64
          example: 1719475216
        updated_at:
          description: Last update time of the policy in epoch time.
          type: integer
          format: int64
          example: 1719475216
    # ------------------------------------
    CustomPoliciesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/CustomPolicyResponseData"
          description: An array of custom policies.
        next_cursor:
          type: string
          description: When a request has more results to return, the next_cursor value is returned as part of the response.
            You can then specify this value as the cursor parameter of a following request.
    # ------------------------------------
    SystemPolicyResponseData:
      type: object
      required:
        - id
        - policy_statement
        - created_at
        - updated_at
        - scope_type
        - name
      properties:
        id:
          description: The unique identifier of the policy.
          type: string
          example: "12jf789l12hwiuencl7aaqey"
        name:
          description: The name of the policy
          type: string
          example: "Read access to Clothing folder"
        description:
          description: A short description of the policy.
          type: string
          nullable: true
          example: "Permit read access to the Clothing folder with external ID asdfjkl12347890."
        scope_type:
          $ref: '#/components/schemas/ScopeTypeEnum'
        permission_type:
          description: |
            Specifies whether the permission applies globally across all resources or contexts within the scope (i.e., security settings for the account, or all folders in a product environment), or specifically to designated content instances (i.e., folder with external ID "fg3841spr").

                - global

                - content
          type: string
          example: global
        policy_statement:
          description: A Cedar policy that permits or forbids a certain action on a certain element to a principal (user,
            group, or API key).
          type: string
          example: permit(principal == Cloudinary::APIKey::"1234",action==Cloudinary::Action::"read",resource is Cloudinary::Folder
            ) when { resource.ancestor_ids.contains("\<folder_id\>") };
        policy_parameters:
          description: |
            For roles with `permission_type` set to `content`, this defines the type of content the role's policies apply to:
            - The content type can be: `folder_id` or `collection_id`.
            - When assigning the role, provide the instance, e.g. `{"folder_id":"asdfjkl12347890"}`. This specification is passed to the `policy_statement` (Cedar).
          type: array
          items:
            type: string
          example: ["folder_id"]
        category:
          description: The category of the policy.
          type: string
          example: "Management"
        sub_category:
          description: The sub-category of the policy.
          type: string
          example: "General operations"
        created_at:
          description: Creation time of the policy in epoch time.
          type: integer
          format: int64
          example: 1719475216
        updated_at:
          description: Last update time of the policy in epoch time.
          type: integer
          format: int64
          example: 1719475216
    # ------------------------------------
    SystemPoliciesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/SystemPolicyResponseData"
          description: An array of system policies.
        next_cursor:
          type: string
          description: When a request has more results to return, the next_cursor value is returned as part of the response.
            You can then specify this value as the cursor parameter of a following request.
    # ------------------------------------
    EffectivePolicy:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the permission policy.
          example: "cld::global::api_keys::manage"
        policy_statement:
          type: string
          description: A Cedar statement that permits or forbids a principal to perform an action on a resource. Refer to
            the [Permissions API guide](permissions_api_guide) for more information.
          example: permit (principal, action, resource == Cloudinary::Feature::"cld::global::api_keys::view");
    # ------------------------------------
    EffectiveRole:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the role.
          example: "custom::global::admin"
        system_policies:
          description: A list of all the predefined permission policies that are associated with this role.
          type: array
          items:
            $ref: "#/components/schemas/EffectivePolicy"
    # ------------------------------------
    Principal:
      type: object
      required:
        - type
        - id
      properties:
        type:
          $ref: '#/components/schemas/PrincipalTypeEnum'
        id:
          type: string
          description: The unique identifier of the principal.
          example: "1234abc"
    # ------------------------------------
    PrincipalRole:
      type: object
      properties:
        principal_type:
          type: string
          description: |
            The type of principal you want to retrieve roles or permission policies for.

            - user

            - group

            - apiKey

            - provisioningKey
          example: user
        principal_id:
          type: string
          description: The unique identifier of the principal.
          example: 1234abc
        roles:
          description: A list of all the roles that are added to this principal.
          type: array
          items:
            $ref: "#/components/schemas/EffectiveRole"
    # ------------------------------------
    EffectivePoliciesResponse:
      type: object
      properties:
        data:
          allOf:
            - type: object
              properties:
                principals:
                  type: array
                  items:
                    $ref: '#/components/schemas/PrincipalRole'
            - type: object
              properties:
                custom_policies:
                  type: array
                  items:
                    $ref: '#/components/schemas/EffectivePolicy'
    # ------------------------------------
    Role:
      type: object
      required:
        - name
      properties:
        name:
          description: The name of the role.
          type: string
          example: "Upload manager"
        description:
          description: A short description of the role.
          nullable: true
          type: string
          example: "Responsible for managing upload presets and uploading new assets."
        system_policy_ids:
          description: |
            A list of system permission policy IDs to be included in the role.

            **Tip:** Get the list of all available predefined policies using the [Get system policies](#tag/policies/get/policies) method.
          type: array
          items:
            type: string
          example:
            - "cld::policy::global::upload_presets::manage"
            - "cld::policy::global::folder_and_asset_management::create_asset"
    # ------------------------------------
    CreateRole:
      allOf:
        - type: object
          required:
            - permission_type
            - scope_type
          properties:
            id:
              description: |
                The unique identifier for the role.

                * **When creating a new role**: If not provided, the system will auto-generate the ID.
                * **When updating a role**: Specify the ID of the role you want to update.

              type: string
              example: "upload_manager_12334565"
            permission_type:
              description: >
                Specifies whether the permission applies globally across all contexts within the scope (i.e., security settings
                for the account, or all folders in a product environment), or specifically to designated content instances
                (i.e., folder with external ID `"fg3841spr"`). **Note:** This attrubute is immutable.

                - global

                - content

              type: string
              example: global
            scope_type:
              $ref: '#/components/schemas/ScopeTypeEnum'
        - $ref: '#/components/schemas/Role'
    # ------------------------------------
    UpdateRole:
      allOf:
        - $ref: '#/components/schemas/Role'
    # ------------------------------------
    RoleResponseData:
      type: object
      required:
        - id
        - name
        - management_type
        - permission_type
        - scope_type
        - created_at
        - updated_at
      properties:
        id:
          description: The unique identifier of the role.
          type: string
          example: "cld::role::prodenv::master_admin"
        name:
          description: The name of the role.
          type: string
          example: "Master admin"
        description:
          description: A short description of the role.
          type: string
          nullable: true
          example: "Full access."
        management_type:
          $ref: '#/components/schemas/ManagementTypeEnum'
        permission_type:
          description: |
            Specifies whether the permission applies globally across all contexts within the scope (i.e., security settings for the account, or all folders in a product environment), or specifically to designated content instances (i.e., folder with external ID "fg3841spr").

                - global

                - content
          type: string
          example: global
        policy_parameters:
          description: |
            For roles with `permission_type` set to `content`, this defines the type of content the role's policies apply to:
            - The content type can be: `folder_id` or `collection_id`.
            - When assigning the role, provide the instance, e.g. `{"folder_id":"asdfjkl12347890"}`. This specification is passed to the `policy_statement` (Cedar).
          type: array
          items:
            type: string
          example:
            - "folder_id"
        scope_type:
          $ref: '#/components/schemas/ScopeTypeEnum'
        created_at:
          description: The permission policy creation timestamp in epoch time.
          type: integer
          format: int64
          example: 1719475216
        updated_at:
          description: The permission policy last updated timestamp in epoch time.
          type: integer
          format: int64
          example: 1719475216
    # ------------------------------------
    RoleResponse:
      type: object
      properties:
        data:
          allOf:
            - type: object
              properties:
                policies:
                  type: array
                  items:
                    $ref: '#/components/schemas/SystemPolicyResponseData'
            - $ref: '#/components/schemas/RoleResponseData'
    # ------------------------------------
    UpdateRolePrincipal:
      type: object
      required:
        - principal_type
        - principal_id
      properties:
        principal_type:
          $ref: '#/components/schemas/PrincipalTypeEnum'
        principal_id:
          type: string
          description: The unique identifier of the principal.
          example: "1234abc"
        scope_id:
          type: string
          description: The ID of a specific product environment where the role is applied. This parameter is only relevant
            if `scope_type` is "prodenv".
          nullable: true
          example: "975l29lz02jt0836fhwi"
        policy_parameters:
          type: object
          description: For roles with `permission_type` set to `content`, provide the ID of the specific folder or collection
            you want the role to apply to, for example, `{"folder_id":"asdfjkl12347890"}`. This specification is passed to
            the `policy_statement`, written in Cedar language.
          example: {"folder_id": "asdfjkl12347890"}
    PrincipalResponseData:
      type: object
      required:
        - id
        - type
      properties:
        id:
          description: The unique identifier of the principal.
          type: string
          example: "1234abc"
        type:
          $ref: '#/components/schemas/PrincipalTypeEnum'
        role_id:
          type: string
        policy_parameters:
          type: object
        scope_type:
          $ref: '#/components/schemas/ScopeTypeEnum'
        scope_id:
          type: string
          nullable: true
        created_at:
          type: integer
          format: int64
        updated_at:
          type: integer
          format: int64
    # ------------------------------------
    PrincipalsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PrincipalResponseData'
          description: An array of principals.
    # ------------------------------------
    RolesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/RoleResponseData'
          description: An array of roles.
    # ------------------------------------
    PrincipalRolesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PrincipalRolesData'
    # ------------------------------------
    PrincipalRolesData:
      type: object
      required:
        - id
        - name
        - management_type
        - permission_type
        - scope_type
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: The unique identifier of the role.
        name:
          type: string
          description: The name of the role.
        description:
          type: string
          nullable: true
          description: A short description of the role.
        management_type:
          $ref: '#/components/schemas/ManagementTypeEnum'
        permission_type:
          $ref: '#/components/schemas/PermissionTypeEnum'
        scope_type:
          $ref: '#/components/schemas/ScopeTypeEnum'
        scope_id:
          type: string
          description: Returned only if the scope type is product environment. Can be "all" to represent all product environments
            or an ID of a specific product environment.
          nullable: true
        policy_parameters:
          type: object
          description: |
            For roles with `permission_type` set to `content`, this defines the type of content the role's policies apply to:
            - The content type can be: `folder_id` or `collection_id`.
            - When assigning the role, provide the instance, e.g. `{"folder_id":"asdfjkl12347890"}`. This specification is passed to the `policy_statement` (Cedar).
          nullable: true
        created_at:
          type: integer
          description: Creation time of the policy in epoch time.
          format: int64
        updated_at:
          type: integer
          description: Last updated time of the policy in epoch time.
          format: int64
    # ------------------------------------
    PrincipalRolesInspectResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            principals:
              type: array
              items:
                $ref: '#/components/schemas/PrincipalRolesInspectData'
        next_cursor:
          type: string
    # ------------------------------------
    PrincipalRolesInspectData:
      type: object
      required:
        - type
        - id
        - roles
      properties:
        type:
          $ref: '#/components/schemas/PrincipalTypeEnum'
        id:
          type: string
          description: The unique identifier of the principal.
        roles:
          type: array
          items:
            $ref: '#/components/schemas/PrincipalRolesData'
    # ------------------------------------
    UpdatePrincipalRolesRequest:
      type: object
      properties:
        operation:
          $ref: '#/components/schemas/OperationEnum'
        principal:
          $ref: '#/components/schemas/Principal'
        roles:
          type: array
          items:
            $ref: '#/components/schemas/RoleToManage'
    # ------------------------------------
    InspectRequest:
      type: object
      required:
        - scope_type
        - principals
      properties:
        scope_type:
          $ref: '#/components/schemas/ScopeTypeEnum'
        scope_id:
          type: string
        principals:
          type: array
          items:
            $ref: '#/components/schemas/Principal'
        policy_parameters:
          type: object
        cursor:
          type: string
    # ------------------------------------
    RoleToManage:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: The unique identifier of the role you want to assign.
          example: "marketing_content_contributor_1357fhe"
        scope_id:
          type: string
          description: The ID of a specific product environment where the policy is applied. This parameter is only relevant
            if `scope_type` is "prodenv".
          example: "975l29lz02jt0836fhwi"
        policy_parameters:
          type: object
          description: Defines the content instance that the role applies to. Specify the content type (`folder_id` or `collection_id`)
            and its corresponding ID. For example, `{"folder_id":"asdfjkl12347890"}`. This specification is passed to the
            `policy_statement` (Cedar).
          example:
            folder_id: "asdfjkl12347890"
    PermissionsErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/PermissionsError'
    # ------------------------------------
    PermissionsError:
      type: object
      properties:
        category:
          type: string
          description: A classification of the error, indicating the general area or type of problem.
        code:
          type: string
          description: A specific error code that uniquely identifies the error condition.
        message:
          type: string
          description: A human-readable message providing a brief explanation of the error and its cause.
        details:
          type: object
          description: Additional contextual information about the error, which may include relevant data.

  # -----------------------------------------------------------------------

  securitySchemes:
    basicAuth:
      type: http
      scheme: basic

  parameters:
    subAccountId:
      name: sub_account_id
      description: The ID of the product environment.
      in: path
      required: true
      schema:
        type: string
      example: "abcde1fghij2klmno3pqrst4uvwxy5z"

    accessKey:
      name: key
      description: The access key (api key).
      in: path
      required: true
      schema:
        type: string
      example: "814814814814814"

    userId:
      name: user_id
      in: path
      description: The ID of the user.
      required: true
      schema:
        type: string
      example: "0abed8dfcc039ea05e2a1d494fd442"

    userGroupId:
      name: group_id
      description: The ID of the user group.
      in: path
      required: true
      schema:
        type: string
      example: "7f08f1f1fc910bf1f25274aef11d27"
    userGroupExtendedDetails:
      in: query
      name: extended_details
      schema:
        type: boolean
      description: |
        Whether to only return extended (true) or basic information about the group (false).
        **Default**: false.
      example: true

    AccountIdParam:
      name: account_id
      description: Account ID
      in: path
      required: true
      schema:
        type: string
      x-speakeasy-globals-hidden: true
    # ------------------------------------
    PolicyIdParam:
      name: policy_id
      description: A unique identifier for the custom permission policy.
      in: path
      required: true
      schema:
        type: string
    # ------------------------------------
    ScopeTypeParam:
      name: scope_type
      description: Specifies the level for retrieving policies or roles, either at the account level or within product environments.
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/ScopeTypeEnum'
    # ------------------------------------
    ScopeTypeRequiredParam:
      name: scope_type
      description: Specifies the level for retrieving policies or roles, either at the account level or within product environments.
      in: query
      required: true
      schema:
        $ref: '#/components/schemas/ScopeTypeEnum'
    # ------------------------------------
    ScopeIdParam:
      name: scope_id
      description: >
        The ID of a specific product environment where the policy is applied. This parameter is only relevant if `scope_type`
        is "prodenv".

        - <product_environment_id>

      in: query
      required: false
      schema:
        type: string
    # ------------------------------------
    PolicyParameterKeyParam:
      name: param_key
      description: The type of content instance the role applies to, either `folder_id` or `collection_id`. Use together with
        `param_value` to retrieve role assignments as they apply to a specific instance.
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
        example:
          - "folder_id"
    # ------------------------------------
    PolicyParameterValueParam:
      name: param_value
      description: The ID of the content instance (for example, a specific folder or collection). Use together with param_key
        to retrieve roles as they apply to a specific instance.
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
        example:
          - "asdfjkl12347890"
    # ------------------------------------
    FolderId:
      name: folder_id
      description: >
        * In the **Get role** endpoint, the specified `folder_id` is included in the `policy_statement` parameter of the response.
        If no `folder_id` is specified, the `policy_statement` shows a placeholder for the `folder_id` where relevant.

        * In the **Get a principal's roles**, **Get a role's principals**, and **Inspect** endpoints, the results are filtered
        by the specified `folder_id`. Only roles or principals with `policy_statement` parameters associated with that `folder_id`
        are returned.
      in: query
      schema:
        type: string
    # ------------------------------------
    AssetId:
      name: asset_id
      description: Not currently supported.
      in: query
      schema:
        type: string
    # ------------------------------------
    CollectionId:
      name: collection_id
      description: >
        * In the **Get role** endpoint, the specified `collection_id` is included in the `policy_statement` parameter of the
        response. If no `collection_id` is specified, the `policy_statement` shows a placeholder for the `collection_id` where
        relevant.

        * In the **Get a principal's roles** and **Get a role's principals** endpoints, the results are filtered by the specified
        `collection_id`. Only roles or principals with `policy_statement` parameters associated with that `collection_id`
        are returned.
      in: query
      schema:
        type: string
    # ------------------------------------
    PolicyParameterTypesParam:
      name: policy_parameters
      description: |
        For roles with `permission_type` set to `content`, this defines the type of content the role's policies apply to:
        - The content type can be: `folder_id` or `collection_id`.
        - When assigning the role, provide the instance, e.g. `{"folder_id":"asdfjkl12347890"}`. This specification is passed to the `policy_statement` (Cedar).
      in: query
      required: false
      content:
        application/json:
          schema:
            type: array
            items:
              type: string
    CursorParam:
      name: cursor
      description: 'A pagination cursor for fetching subsequent results.'
      in: query
      schema:
        type: string
    # ------------------------------------
    EnabledParam:
      name: enabled
      description: 'Filter policies by enabled status (true/false).'
      in: query
      schema:
        type: boolean
        nullable: true
    # -----------------------------------------------------------------------
    PrincipalTypeParam:
      name: principal_type
      description: "The type of principal you want to retrieve roles or permission policies for."
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/PrincipalTypeEnum'
    # ------------------------------------
    PrincipalTypeRequiredParam:
      name: principal_type
      description: "The type of principal you want to retrieve roles or permission policies for."
      in: query
      required: true
      schema:
        $ref: '#/components/schemas/PrincipalTypeEnum'
    # ------------------------------------
    PrincipalIdParam:
      name: principal_id
      description: |
        The unique identifier of the principal you want to retrieve roles or permission policies for.

        **Notes:**

        * This parameter is mandatory if `principal_type` is provided.
        * Ensure the specified ID belongs to a principle of the specified type.
      in: query
      schema:
        type: string
    # ------------------------------------
    PrincipalIdRequiredParam:
      name: principal_id
      description: |
        The unique identifier of the principal you want to retrieve roles or permission policies for.

        **Notes:**

        * This parameter is mandatory if `principal_type` is provided.
        * Ensure the specified ID belongs to a principle of the specified type.
      in: query
      required: true
      schema:
        type: string
    # ------------------------------------
    PermissionTypeParam:
      name: permission_type
      description: Specifies whether to retrieve roles whose permissions apply globally across all contexts within the scope
        (i.e., security settings for the account, or all folders in a product environment), or specifically to designated
        content instances (i.e., folder with external ID "fg3841spr").
      in: query
      required: true
      schema:
        $ref: '#/components/schemas/PermissionTypeEnum'
    # ------------------------------------
    PermissionTypeOptionalParam:
      name: permission_type
      description: Specifies whether to retrieve roles whose permissions apply globally across all contexts within the scope
        (i.e., security settings for the account, or all folders in a product environment), or specifically to designated
        content instances (i.e., folder with external ID "fg3841spr").
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/PermissionTypeEnum'
    # ------------------------------------
    ManagementTypeParam:
      name: management_type
      description: Specifies whether the role's policies are managed by Cloudinary (`system`) or by the user (`custom`).
      in: query
      schema:
        $ref: '#/components/schemas/ManagementTypeEnum'
    # ------------------------------------
    ForceDeleteParam:
      name: force
      description: >
        Determines whether the role should be deleted when it has associated principals.

        - `true`: Deletes the role even if it has associated principals.

        - `false` (default): Prevents deletion if the role has associated principals. You must manually unassociate the principals
        before deleting the role.
      in: query
      schema:
        type: boolean
    # ------------------------------------
    RoleIdParam:
      name: role_id
      description: A unique identifier for the role.
      in: path
      required: true
      schema:
        type: string
    # -----------------------------------------------------------------------
    VerboseParam:
      name: verbose
      description: Determines whether the response contains all the parameters described below (`true`), or only `id` and
        `principal_type` (`false`). *Default:* `false`
      in: query
      schema:
        type: boolean
    # ------------------------------------

  responses:
    400BadRequest:
      description: Bad request.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

    401Unauthorized:
      description: Authorization required.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error:
              message: "Invalid credentials"

    403NotAllowed:
      description: Not allowed.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

    404NotFound:
      description: Not found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error:
              message: "not found"

    409AlreadyExists:
      description: Already exists.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

    420MaxUsageRateExceeded:
      description: Max usage rate exceeded.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    429TooManyRequests:
      description: Too many requests.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

  examples:
    ProductEnvironment1:
      summary: Product environment sample response 1
      value:
        cloud_name: "product1"
        name: "Product1 Application"
        enabled: true
        id: "abcde1fghij2klmno3pqrst4uvwxy5z"
        api_access_keys:
          - key: "123456789012345"
            secret: "asdf1JKL2xyz3ABc4s3c5reT01DfaKez"
            enabled: true
        created_at: "2016-09-27T08:00:16Z"
        updated_at: "2016-09-27T08:00:16Z"

    ProductEnvironment2:
      summary: Product environment sample response 2
      value:
        cloud_name: "product2"
        name: "Product2 Application"
        enabled: true
        id: "0aaaaa1bbbbb2ccccc3ddddd4eeeee5f"
        api_access_keys:
          - key: "543210987654321"
            secret: "T415i5mYs3cr3TkeYN0tR3a77y0o0"
            enabled: true
        created_at: "2016-03-15T11:44:48Z"
        updated_at: "2016-03-15T11:44:48Z"

    ProductEnvironment3:
      summary: Product environment sample response 3
      value:
        cloud_name: "product3"
        name: "Product3 Application"
        enabled: false
        id: "555asdf0000zxcvb3456qwerty"
        api_access_keys:
          - key: "135792468054321"
            secret: "w4aTi5Y0u6k3YN0773lL1nGyUt0Da8"
            enabled: true
        created_at: "2016-09-27T11:15:35Z"
        updated_at: "2016-09-27T11:15:35Z"

    ProductEnvironments:
      summary: Get product environments sample response
      value:
        sub_accounts:
          - cloud_name: "product1"
            name: "Product1 Application"
            enabled: true
            id: "abcde1fghij2klmno3pqrst4uvwxy5z"
            api_access_keys:
              - key: "123456789012345"
                secret: "asdf1JKL2xyz3ABc4s3c5reT01DfaKez"
                enabled: true
            created_at: "2016-09-27T08:00:16Z"
            updated_at: "2016-09-27T08:00:16Z"
          - cloud_name: "product2"
            name: "Product2 Application"
            enabled: true
            id: "0aaaaa1bbbbb2ccccc3ddddd4eeeee5f"
            api_access_keys:
              - key: "543210987654321"
                secret: "T415i5mYs3cr3TkeYN0tR3a77y0o0"
                enabled: true
            created_at: "2016-03-15T11:44:48Z"
            updated_at: "2016-03-15T11:44:48Z"

    MainAccessKey:
      summary: Access key sample value
      value:
        name: "main_key"
        api_key: "814814814814814"
        api_secret: "QcsQcsQcsQcsQcsQcsQcsQcsQcs"
        created_at: "2022-03-15T11:44:48Z"
        updated_at: "2023-08-10T09:23:45Z"
        enabled: true

    AccessKeys:
      summary: Get access keys sample response
      value:
        access_keys:
          - name: "main_key"
            api_key: "814814814814814"
            api_secret: "QcsQcsQcsQcsQcsQcsQcsQcsQcs"
            created_at: "2022-03-15T11:44:48Z"
            updated_at: "2023-08-10T09:23:45Z"
            enabled: true
          - name: "secondary_key"
            api_key: "418418418418418"
            api_secret: "scQscQscQscQscQscQscQscQscQ"
            created_at: "2023-09-10T09:23:45Z"
            updated_at: "2023-09-10T09:45:57Z"
            enabled: false
        total: 2

    UserJohn:
      summary: User details example
      value:
        id: "0abed8dfcc039ea05e2a1d494fd442"
        name: John
        role: technical_admin
        email: john@example.com
        pending: true
        enabled: true
        created_at: '2020-09-03T13:33:25Z'
        updated_at: '2020-09-03T13:33:25Z'
        all_sub_accounts: true

    CreateUserExample:
      summary: Create user
      value:
        name: jenny_bar
        role: master_admin
        email: jenny_bar@example.com

    UserResponseExample:
      summary: User details example
      value:
        id: "7f08f1f1fc910bf1f25274aef11d27"
        name: jenny_bar
        role: master_admin
        email: jenny_bar@example.com
        pending: true
        enabled: true
        created_at: '2019-09-12T11:53:57Z'
        updated_at: '2019-09-12T11:53:57Z'
        last_login: '2022-01-11T15:11:04Z'
        all_sub_accounts: true

    Users:
      summary: Get users sample response
      value:
        users:
          - id: 139147faa12ce11f22cfaffa84b307
            name: john_smith
            role: media_library_user
            email: john_smith@example.com
            pending: true
            enabled: true
            created_at: "2020-01-13T05:16:06Z"
            updated_at: "2020-01-13T05:16:06Z"
            last_login: "2022-01-11T15:11:04Z"
            all_sub_accounts: true
          - id: 28c84b2aa7924a5e64f949b5403981
            name: john_jones
            role: master_admin
            email: john_jones@example.com
            pending: true
            enabled: true
            created_at: "2019-01-13T05:16:05Z"
            updated_at: "2019-01-13T05:16:05Z"
            last_login: "2021-11-12T15:11:02Z"
            all_sub_accounts: true

    UserGroupDesigners:
      summary: User group example
      value:
        id: "7f08f1f1fc910bf1f25274aef11d27"
        name: "Designers"
    UserGroupDesignersExtendedDetails:
      summary: User group extended details example
      value:
        id: "7f08f1f1fc910bf1f25274aef11d27"
        name: "Designers"
        users:
          - id: "0abed8dfcc039ea05e2a1d494fd442"
            name: John Doe
            email: john.doe@example.com
          - id: "asdf1234uiopjkl7890wernmjlcaeg"
            name: Harry Potts
            email: harry.potts@example.com
        created_at: "2016-09-27T08:00:16Z"
        updated_at: "2016-09-27T08:00:16Z"

    UserGroupDesignersRequest:
      summary: User group update example
      value:
        name: "Designers and Creatives"
    UserGroupUpdate:
      summary: User group update example
      value:
        id: "7f08f1f1fc910bf1f25274aef11d27"
        name: "Designers and Creatives"
    UserGroups:
      summary: Get user groups example
      value:
        user_groups:
          - id: "7f08f1f1fc910bf1f25274aef11d27"
            name: "user_group_1"
          - id: "1cc3808888154263ac1e5eb2e5c52d61"
            name: "user_group_2"
    UserGroupsList:
      summary: Get user groups for a user example
      value:
        groups:
          - id: "7f08f1f1fc910bf1f25274aef11d27"
            name: "user_group_1"
          - id: "1cc3808888154263ac1e5eb2e5c52d61"
            name: "user_group_2"
    UserSubAccounts:
      summary: Get sub-accounts for a user example
      value:
        sub_accounts:
          - id: "abcde1fghij2klmno3pqrst4uvwxy5z"
            name: "Product1 Application"
            description: "Main product environment"
            cloud_name: "product1"
            enabled: true
          - id: "0aaaaa1bbbbb2ccccc3ddddd4eeeee5f"
            name: "Product2 Application"
            description: "Secondary product environment"
            cloud_name: "product2"
            enabled: true
    UserGroupsExtendedDetails:
      summary: Get user groups extended details example
      value:
        user_groups:
          - id: "7f08f1f1fc910bf1f25274aef11d27"
            name: "user_group_1"
            users:
              - id: "0abed8dfcc039ea05e2a1d494fd442"
                name: John Doe
                email: john.doe@example.com
              - id: "asdf1234uiopjkl7890wernmjlcaeg"
                name: Harry Potts
                email: harry.potts@example.com
            created_at: "2016-09-27T08:00:16Z"
            updated_at: "2016-09-27T08:00:16Z"
          - id: "1cc3808888154263ac1e5eb2e5c52d61"
            name: "user_group_2"
            users:
              - id: "asdl23uioejafmckowpuafdaghjajw"
                name: Beth Poppins
                email: beth.poppins@example.com
              - id: "iwejfjiwl83882kkswionvnnlxloow"
                name: Mike Smith
                email: mike.smith@example.com
            created_at: "2016-09-27T08:00:16Z"
            updated_at: "2016-09-27T08:00:16Z"
    UserGroupUserJohn:
      summary: User group user example
      value:
        id: "0abed8dfcc039ea05e2a1d494fd442"
        name: John Doe
        email: john.doe@example.com
    UserGroupUsers:
      summary: User group users example
      value:
        users:
          - id: "0abed8dfcc039ea05e2a1d494fd442"
            name: John
            email: john@example.com

    UserGroupUsersNoJohn:
      summary: User group users example
      value:
        users: []

    # The following are all valid examples of BillingUsageResponse for different plans and scenarios.
    BillingUsageResponse_ProPAYG:
      summary: Get billing usage example for a Pro PAYG plan
      value:
        - plan_name: "Pro PAYG"
          metric_usage:
            - metric: "credit"
              limit: 2750
              cycles:
                - from_day: "2024-08-21"
                  to_day: "2024-09-20"
                  usage: 25641.55
                  breakdown:
                    storage_image: 7971.55
                    storage_video: 1575.58
                    storage_raw: 0
                    transformations_image: 9603.73
                    transformations_video: 2290.76
                    bandwidth_image: 2972.57
                    bandwidth_video: 1227.22
                    bandwidth_raw: 0.14
                  product_environment_breakdown:
                    - storage_image: 0.04
                      storage_video: 0.09
                      storage_raw: 0
                      transformations_image: 0
                      transformations_video: 0
                      bandwidth_image: 0
                      bandwidth_video: 0
                      bandwidth_raw: 0
                      cloud_name: "myproduct"
    BillingUsageResponse_AdvancedExtraPAYG:
      summary: Get billing usage example for an Advanced Extra PAYG + plan
      value:
        - plan_name: "Advanced Extra PAYG +"
          metric_usage:
            - metric: "credit"
              limit: 1350
              cycles:
                - from_day: "2025-02-05"
                  to_day: "2025-03-04"
                  usage: 2300
                  breakdown:
                    storage_image: 517.71
                    storage_video: 0.22
                    storage_raw: 0
                    transformations_image: 59.39
                    transformations_video: 0
                    video_seconds: 790.21
                    bandwidth_raw: 0
                    image_impressions: 932.46
                  product_environment_breakdown:
                    - storage_image: 0.04
                      storage_video: 0.11
                      storage_raw: 0
                      transformations_image: 0
                      transformations_video: 0
                      video_seconds: 0
                      bandwidth_raw: 0
                      image_impressions: 0
                      cloud_name: "myproduct1"
                    - storage_image: 517.67
                      storage_video: 0.11
                      storage_raw: 0
                      transformations_image: 59.39
                      transformations_video: 0
                      video_seconds: 790.21
                      bandwidth_raw: 0
                      image_impressions: 932.46
                      cloud_name: "myproduct2"
    BillingUsageResponse_AdvancedPAYG:
      summary: Get billing usage example for an Advanced PAYG plan
      value:
        - plan_name: "Advanced PAYG"
          metric_usage:
            - metric: "credit"
              limit: 600
              cycles:
                - from_day: "2024-08-26"
                  to_day: "2024-09-18"
                  usage: 1830.25
                  breakdown:
                    storage_image: 1.98
                    storage_video: 0.43
                    storage_raw: 0.01
                    transformations_image: 0.4
                    transformations_video: 0
                    bandwidth_image: 1827.43
                    bandwidth_video: 0
                    bandwidth_raw: 0
                  product_environment_breakdown:
                    - storage_image: 1.98
                      storage_video: 0.43
                      storage_raw: 0.01
                      transformations_image: 0.4
                      transformations_video: 0
                      bandwidth_image: 1827.43
                      bandwidth_video: 0
                      bandwidth_raw: 0
                      cloud_name: "myproduct"
    BillingUsageResponse_ProPAYGPlus:
      summary: Get billing usage example for a Pro PAYG + plan
      value:
        - plan_name: "Pro PAYG +"
          metric_usage:
            - metric: "credit"
              limit: 2750
              cycles:
                - from_day: "2025-01-14"
                  to_day: "2025-02-04"
                  usage: 1718.16
                  breakdown:
                    storage_image: 642.18
                    storage_video: 0.24
                    storage_raw: 0
                    transformations_image: 59.66
                    transformations_video: 0
                    video_seconds: 0.02
                    bandwidth_raw: 0
                    image_impressions: 1016.06
                  product_environment_breakdown:
                    - storage_image: 0.05
                      storage_video: 0.14
                      storage_raw: 0
                      transformations_image: 0
                      transformations_video: 0
                      video_seconds: 0
                      bandwidth_raw: 0
                      image_impressions: 0
                      cloud_name: "myproduct1"
                    - storage_image: 642.13
                      storage_video: 0.1
                      storage_raw: 0
                      transformations_image: 59.66
                      transformations_video: 0
                      video_seconds: 0.02
                      bandwidth_raw: 0
                      image_impressions: 1016.06
                      cloud_name: "myproduct2"
    BillingUsageResponse_MultiPlan:
      summary: Get billing usage example for multiple plans in a single response
      value:
        - plan_name: "Advanced PAYG"
          metric_usage:
            - metric: "credit"
              limit: 600
              cycles:
                - from_day: "2024-08-26"
                  to_day: "2024-09-18"
                  usage: 1830.25
                  breakdown:
                    storage_image: 1.98
                    storage_video: 0.43
                    storage_raw: 0.01
                    transformations_image: 0.4
                    transformations_video: 0
                    bandwidth_image: 1827.43
                    bandwidth_video: 0
                    bandwidth_raw: 0
                  product_environment_breakdown:
                    - storage_image: 1.98
                      storage_video: 0.43
                      storage_raw: 0.01
                      transformations_image: 0.4
                      transformations_video: 0
                      bandwidth_image: 1827.43
                      bandwidth_video: 0
                      bandwidth_raw: 0
                      cloud_name: "myproduct"
        - plan_name: "Advanced Extra PAYG"
          metric_usage:
            - metric: "credit"
              limit: 1350
              cycles:
                - from_day: "2024-09-19"
                  to_day: "2024-09-25"
                  usage: 1133.49
                  breakdown:
                    storage_image: 4.25
                    storage_video: 0.91
                    storage_raw: 0.02
                    transformations_image: 0.27
                    transformations_video: 0
                    bandwidth_image: 1128.03
                    bandwidth_video: 0
                    bandwidth_raw: 0
                  product_environment_breakdown:
                    - storage_image: 4.25
                      storage_video: 0.91
                      storage_raw: 0.02
                      transformations_image: 0.27
                      transformations_video: 0
                      bandwidth_image: 1128.03
                      bandwidth_video: 0
                      bandwidth_raw: 0
                      cloud_name: "myproduct"
    CustomPoliciesExample:
      summary: Custom policies example
      value:
        data:
          - id: "12jf789l12hwiuencl7aaqey"
            policy_statement: permit(principal == Cloudinary::APIKey::"1234",action==Cloudinary::Action::"read",resource is
              Cloudinary::Folder ) when {resource.ancestor_ids.contains("asdfjkl12347890")} ;
            description: "Permit read access to the Clothing folder with external ID asdfjkl12347890."
            scope_type: "prodenv"
            scope_id: "975l29lz02jt0836fhwi"
            name: "Read access to Clothing folder"
            enabled: true
            created_at: 1719475216
            updated_at: 1719475216
          - id: "13890asdhjfqyewiurzbxn273"
            policy_statement: permit(principal == Cloudinary::APIKey::"1234",action==Cloudinary::Action::"update",resource
              is Cloudinary::Folder ) when {resource.ancestor_ids.contains("asdfjkl12347890")} ;
            description: "Permit updating the Clothing folder with external ID asdfjkl12347890."
            scope_type: "prodenv"
            scope_id: "975l29lz02jt0836fhwi"
            name: "Update access to Clothing folder"
            enabled: true
            created_at: 1719475216
            updated_at: 1719475216

    CustomPolicyExample:
      summary: Custom policy example
      value:
        data:
          id: "12jf789l12hwiuencl7aaqey"
          policy_statement: permit(principal == Cloudinary::APIKey::"1234",action==Cloudinary::Action::"read",resource is
            Cloudinary::Folder ) when {resource.ancestor_ids.contains("asdfjkl12347890")} ;
          description: "Permit read access to the Clothing folder with external ID asdfjkl12347890."
          scope_type: "prodenv"
          scope_id: "975l29lz02jt0836fhwi"
          name: "Read access to Clothing folder"
          enabled: true
          created_at: 1719475216
          updated_at: 1719475216

    SystemPoliciesExample:
      summary: Get system policies example
      value:
        data:
          - id: "cld::policy::global::assets::moderate"
            name: "Moderate all assets"
            description: "Approve and reject all assets in moderation. To perform these actions from the Moderation page,
              pair this permission with 'Access the Moderation page'. To view assets on the page, pair it with the 'View all
              folders and assets' global permission."
            scope_type: "prodenv"
            permission_type: "global"
            policy_statement: permit(principal, action == Cloudinary::Action::"moderate", resource is Cloudinary::Asset);
            created_at: 1719475216
            updated_at: 1719475216

          - id: "cld::policy::content::folder::view_download"
            name: "View all assets"
            description: "View all assets in the folder and its nested subfolders."
            scope_type: "prodenv"
            permission_type: "content"
            policy_statement: |
              permit(principal, action == Cloudinary::Action::"read", resource is Cloudinary::Folder) when { resource.ancestor_ids.contains("<folder_id>") };
              permit(principal, action == Cloudinary::Action::"read", resource is Cloudinary::Asset) when { resource.ancestor_ids.contains("<folder_id>") };
            policy_parameters: ["folder_id"]
            created_at: 1719475216
            updated_at: 1719475216
        next_cursor: "3"

    EffectivePoliciesExample:
      summary: Get effective policies example
      value:
        data:
          principals:
            - principal_type: "user"
              principal_id: "1234abc"
              roles:
                - id: "upload_manager_12334565"
                  system_policies:
                    - id: "cld::policy::global::upload_presets::manage"
                      policy_statement: "permit (principal == Cloudinary::user::\"1234abc\", action == Cloudinary::Action::\"\
                        read\", resource is Cloudinary::UploadPreset);"
                    - id: "cld::policy::global::folder_and_asset_management::create_asset"
                      policy_statement: |
                        permit(principal == Cloudinary::user::\"1234abc\", action, resource is Cloudinary::UploadPreset);
                        permit(principal == Cloudinary::user::\"1234abc\", action, resource is Cloudinary::UploadMapping);
                        permit(principal == Cloudinary::user::\"1234abc\", action == Cloudinary::Action::"update_settings", resource is Cloudinary::ProductEnvironment);
                        permit(principal == Cloudinary::user::\"1234abc\", action, resource == Cloudinary::Feature::"cld::global::upload_settings::manage");
                        permit(principal == Cloudinary::user::\"1234abc\", action, resource == Cloudinary::Feature::"cld::global::upload_settings::access");
                - id: "cld::role::prodenv::reports"
                  system_policies:
                    - id: "cld::policy::global::reports::delivery::view"
                      policy_statement: |
                        permit(principal == Cloudinary::user::\"1234abc\", action, resource == Cloudinary::Feature::"cld::global::reports::delivery::view");
                        permit(principal == Cloudinary::user::\"1234abc\", action == Cloudinary::Action::"read", resource is Cloudinary::Report) when {resource.type == "delivery"};
                    - id: "cld::policy::global::reports::errors::view"
                      policy_statement: "permit (pprincipal == Cloudinary::user::\"1234abc\", action, resource == Cloudinary::Feature::\"\
                        cld::global::reports::errors::view\");"
                    - id: "cld::policy::global::reports::usage::view"
                      policy_statement: |
                        permit (principal == Cloudinary::user::\"1234abc\", action, resource == Cloudinary::Feature::"cld::global::reports::usage::view");
                        permit (principal == Cloudinary::user::\"1234abc\", action == Cloudinary::Action::"read", resource is Cloudinary::Report) when { resource.type == "env_usage" };
          custom_policies:
            - id: "12jf789l12hwiuencl7aaqey"
              policy_statement: "permit(principal == Cloudinary::user::\"1234abc\", action == Cloudinary::Action::\"read\"\
                , resource is Cloudinary::Folder) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")};"
            - id: "12jf789l12hwiuencl7aaqey"
              policy_statement: "permit(principal == Cloudinary::user::\"1234abc\", action == Cloudinary::Action::\"update\"\
                , resource is Cloudinary::Folder) when {resource.ancestor_ids.contains(\"asdfjkl12347890\")};"

    CreateCustomPolicyExample:
      summary: Create custom policy example
      value:
        policy_statement: permit(principal == Cloudinary::APIKey::"1234",action==Cloudinary::Action::"read",resource is Cloudinary::Folder
          ) when {resource.ancestor_ids.contains("asdfjkl12347890")} ;
        description: "Permit read access to the Clothing folder with external ID asdfjkl12347890."
        scope_type: "prodenv"
        scope_id: "975l29lz02jt0836fhwi"
        name: "Read access to Clothing folder"
        enabled: true

    # ------------------------------------
    CreateCustomPolicyResponseExample:
      summary: Custom policy created successfully
      value:
        data:
          id: "12jf789l12hwiuencl7aaqey"
          policy_statement: permit(principal == Cloudinary::APIKey::"1234",action==Cloudinary::Action::"read",resource is
            Cloudinary::Folder ) when {resource.ancestor_ids.contains("asdfjkl12347890")} ;
          description: "Permit read access to the Clothing folder with external ID asdfjkl12347890."
          scope_type: "prodenv"
          scope_id: "975l29lz02jt0836fhwi"
          name: "Read access to Clothing folder"
          enabled: true
          created_at: 1719475216
          updated_at: 1719475216
    # ------------------------------------
    UpdateCustomPolicyExample:
      summary: Update custom policy example
      value:
        policy_statement: permit(principal == Cloudinary::APIKey::"1234",action==Cloudinary::Action::"read",resource is Cloudinary::Folder
          ) when {resource.ancestor_ids.contains("asdfjkl12347890")} ;
        description: "Permit read access to the Accessories folder with external ID asdfjkl12347890."
        scope_type: "prodenv"
        scope_id: "975l29lz02jt0836fhwi"
        name: "Read access to Accessories folder"
        enabled: true
    # ------------------------------------
    UpdateCustomPolicyResponseExample:
      summary: Custom policy updated successfully
      value:
        data:
          id: "12jf789l12hwiuencl7aaqey"
          policy_statement: permit(principal == Cloudinary::APIKey::"1234",action==Cloudinary::Action::"read",resource is
            Cloudinary::Folder ) when {resource.ancestor_ids.contains("asdfjkl12347890")} ;
          description: "Permit read access to the Accessories folder with external ID asdfjkl12347890."
          scope_type: "prodenv"
          scope_id: "975l29lz02jt0836fhwi"
          name: "Read access to Accessories folder"
          enabled: true
          created_at: 1719475216
          updated_at: 1719475216
    # ------------------------------------
    GetRolesExample:
      summary: Get roles example
      value:
        data:
          - id: "cld::role::account::master_admin"
            name: "Master Admin"
            description: "Manage all account-level settings and features."
            management_type: "system"
            permission_type: "global"
            scope_type: "account"
            created_at: 1719475216
            updated_at: 1719475216

          - id: "cld::role::account::admin"
            name: "Admin"
            description: "Manage roles, users, and groups, and access Cloudinary products."
            management_type: "system"
            permission_type: "global"
            scope_type: "account"
            created_at: 1719475216
            updated_at: 1719475216

          - id: "custom::role::account::admin_assist"
            name: "Admin"
            description: "View roles, users and groups, and account-level reports."
            management_type: "custom"
            permission_type: "global"
            scope_type: "account"
            created_at: 1719475216
            updated_at: 1719475216

          - id: "cld::role::prodenv::ml_user"
            name: "Media Library User"
            description: "Access specific folders and collections according to assigned permissions."
            management_type: "system"
            permission_type: "global"
            scope_type: "prodenv"
            created_at: 1719475216
            updated_at: 1719475216
    # ------------------------------------
    GetRoleExample:
      summary: Get role example
      value:
        data:
          policies:
            - id: "cld::policy::global::upload_presets::manage"
              name: "Manage upload settings"
              description: "View, create, modify, or delete upload settings, such as upload presets, upload mappings, and
                upload defaults."
              scope_type: "prodenv"
              permission_type: "global"
              policy_statement: |
                permit(principal, action, resource is Cloudinary::UploadPreset);
                permit(principal, action, resource is Cloudinary::UploadMapping);
                permit(principal, action == Cloudinary::Action::"update_settings", resource is Cloudinary::ProductEnvironment);
                permit(principal, action, resource == Cloudinary::Feature::"cld::global::upload_settings::manage");
                permit(principal, action, resource == Cloudinary::Feature::"cld::global::upload_settings::access");
              category: Settings
              sub_category: Upload Settings
              created_at: 1719475215
              updated_at: 1719475215
            - id: "cld::policy::global::folder_and_asset_management::create_asset"
              name: "Upload assets"
              description: "Upload assets to any folder, including the root, without requiring specific folder permissions.
                Includes the option to select an upload preset and apply tags and metadata."
              scope_type: "prodenv"
              permission_type: "global"
              policy_statement: permit(principal, action in [Cloudinary::Action::"create"], resource is Cloudinary::Asset);
              category: Management
              sub_category: Folder and asset management
              created_at: 1719475215
              updated_at: 1719475215
          id: "upload_manager_12334565"
          name: "Upload manager"
          description: "Responsible for managing upload settings and uploading new assets."
          management_type: "custom"
          permission_type: "global"
          scope_type: "prodenv"
          created_at: 1719475216
          updated_at: 1719475216
    # ------------------------------------
    CreateGlobalRoleResponseExample:
      summary: Global role created successfully
      value:
        data:
          policies:
            - id: "cld::policy::global::upload_presets::manage"
              name: "Manage upload settings"
              description: "View, create, modify, or delete upload settings, such as upload presets, upload mappings, and
                upload defaults."
              scope_type: "prodenv"
              permission_type: "global"
              policy_statement: permit (principal, action in [Cloudinary::Action::"create", Cloudinary::Action::"read", Cloudinary::Action::"update",
                Cloudinary::Action::"delete"], resource is Cloudinary::UploadPreset);
              category: "Settings"
              sub_category: "Upload Settings"
              created_at: 1719475215
              updated_at: 1719475215
            - id: "cld::policy::global::folder_and_asset_management::create_asset"
              name: "Upload assets"
              description: "Upload assets to any folder, including the root, without requiring specific folder permissions.
                Includes the option to select an upload preset and apply tags and metadata. "
              scope_type: "prodenv"
              permission_type: "global"
              policy_statement: permit ( principal, action in [Cloudinary::Action::"create", Cloudinary::Action::"read"],
                resource is Cloudinary::Asset) permit ( principal, action in [Cloudinary::Action::"create", Cloudinary::Action::"read"],
                resource is Cloudinary::Folder)
              category: "Management"
              sub_category: "Folder and asset management"
              created_at: 1719475215
              updated_at: 1719475215
          id: "upload_manager_12334565"
          name: "Upload manager"
          description: "Responsible for managing upload presets and uploading new assets."
          management_type: "custom"
          permission_type: "global"
          scope_type: "prodenv"
          created_at: 1719475216
          updated_at: 1719475216
    # ------------------------------------
    CreateContentRoleResponseExample:
      summary: Content role created successfully
      value:
        data:
          policies:
            - id: "cld::policy::content::folder::view_download"
              name: "View all assets"
              description: "View all assets in the folder and its nested subfolders."
              scope_type: "prodenv"
              permission_type: "content"
              policy_statement: >
                permit(principal, action == Cloudinary::Action::"read", resource is Cloudinary::Folder) when { resource.ancestor_ids.contains("<folder_id>")
                };
                permit(principal, action == Cloudinary::Action::"read", resource is Cloudinary::Asset) when { resource.ancestor_ids.contains("<folder_id>")
                };
              policy_parameters: ["folder_id"]
              category: "Folder"
              sub_category: "View and download"
              created_at: 1719475215
              updated_at: 1719475215
            - id: "cld::policy::content::folder::add_assets"
              name: "Add assets"
              description: "Add assets to the folder by uploading new files, saving an asset as new, or moving existing assets
                from other folders. Tags and structured metadata can be applied during upload."
              scope_type: "prodenv"
              permission_type: "content"
              policy_statement: >
                permit(principal, action == Cloudinary::Action::"create", resource is Cloudinary::Asset) when { resource.ancestor_ids.contains("<folder_id>")};
              policy_parameters: ["folder_id"]
              category: "Folder"
              sub_category: "Contribute"
              created_at: 1719475215
              updated_at: 1719475215
          id: "marketing_content_contributor_1357fhe"
          name: "Marketing content contributor"
          description: "View all assets in selected folders and contribute to those folders, without permission to download."
          management_type: "custom"
          permission_type: "content"
          policy_parameters: ["folder_id"]
          scope_type: "prodenv"
          created_at: 1719475216
          updated_at: 1719475216
    # ------------------------------------
    CreateAcctRoleResponseExample:
      summary: Account-level role created successfully
      value:
        data:
          policies:
            - id: "cld::policy::global::users_and_groups::manage"
              name: "Manage users and groups"
              description: "View, add, and remove users and groups in the account, and manage group memberships."
              scope_type: "account"
              permission_type: "global"
              policy_statement: >
                permit (principal, action , resource is Cloudinary::User);
                permit (principal, action, resource is Cloudinary::Group);
                permit (principal, action, resource == Cloudinary::Feature::"cld::global::users::view");
                permit (principal, action, resource == Cloudinary::Feature::"cld::global::users::create");
                permit (principal, action, resource == Cloudinary::Feature::"cld::global::users::update");
                permit (principal, action, resource == Cloudinary::Feature::"cld::global::users::delete");
                permit (principal, action, resource == Cloudinary::Feature::"cld::global::groups::view");
                permit (principal, action, resource == Cloudinary::Feature::"cld::global::groups::create");
                permit (principal, action, resource == Cloudinary::Feature::"cld::global::groups::update");
                permit (principal, action, resource == Cloudinary::Feature::"cld::global::groups::delete");
              category: "Settings"
              sub_category: "User Management"
              created_at: 1719475215
              updated_at: 1719475215
            - id: "cld::policy::global::account_security::manage"
              name: "Manage account security settings"
              description: "Define account-wide security settings related to authentication, access control, and user privacy."
              scope_type: "account"
              policy_statement: >
                permit (principal, action, resource == Cloudinary::Feature::"cld::global::account::view");
                permit (principal, action, resource == Cloudinary::Feature::"cld::global::account::update");
                permit (principal, action == Cloudinary::Action::"read", resource is Cloudinary::Account);
                permit (principal, action == Cloudinary::Action::"update", resource is Cloudinary::Account);
              category: "Settings"
              sub_category: "Account Security"
              created_at: 1719475215
              updated_at: 1719475215
          id: "sensitive_account_details_manager_88825hl"
          name: "Sensitive account details manager"
          description: "Responsible for managing users and account security."
          management_type: "custom"
          permission_type: "global"
          scope_type: "account"
          created_at: 1719475216
          updated_at: 1719475216
    # ------------------------------------
    UpdateRoleExample:
      summary: Update role example
      value:
        name: "Upload manager"
        description: "Responsible for managing uploads and uploading new assets."
        system_policy_ids:
          - "cld::policy::global::upload_presets::manage"
          - "cld::policy::global::folder_and_asset_management::create_asset"
    # ------------------------------------
    CreateGlobalRoleExample:
      summary: Create global role example
      value:
        id: upload_manager_12334565
        permission_type: "global"
        scope_type: "prodenv"
        name: "Upload manager"
        description: "Responsible for managing uploads and uploading new assets."
        system_policy_ids:
          - "cld::policy::global::upload_presets::manage"
          - "cld::policy::global::folder_and_asset_management::create_asset"
    # ------------------------------------
    CreateAcctRoleExample:
      summary: Create account role example
      value:
        id: sensitive_account_details_manager_88825hl
        permission_type: "global"
        scope_type: "account"
        name: "Sensitive account details manager"
        description: "Responsible for managing users and account security."
        system_policy_ids:
          - "cld::global::users_and_groups::manage"
          - "cld::policy::global::account_security::manage"
    # ------------------------------------
    CreateContentRoleExample:
      summary: Create content role example
      value:
        id: marketing_content_contributor_1357fhe
        permission_type: "content"
        scope_type: "prodenv"
        name: "Marketing content contributor"
        description: "View all assets in selected folders and contribute to those folders, without permission to download."
        system_policy_ids:
          - "cld::policy::content::folder::view_download"
          - "cld::policy::content::folder::add_assets"
    # ------------------------------------
    UpdateRoleResponseExample:
      summary: Role updated successfully
      value:
        data:
          policies:
            - id: "cld::policy::global::upload_presets::manage"
              name: "Manage upload settings"
              description: "View, create, modify, or delete upload settings, such as upload presets, upload mappings, and
                upload defaults."
              scope_type: "prodenv"
              permission_type: "global"
              policy_statement: |
                permit(principal, action, resource is Cloudinary::UploadPreset);
                permit(principal, action, resource is Cloudinary::UploadMapping);
                permit(principal, action == Cloudinary::Action::"update_settings", resource is Cloudinary::ProductEnvironment);
                permit(principal, action, resource == Cloudinary::Feature::"cld::global::upload_settings::manage");
                permit(principal, action, resource == Cloudinary::Feature::"cld::global::upload_settings::access");
              category: "Settings"
              sub_category: "Upload Settings"
              created_at: 1719475215
              updated_at: 1719475215
            - id: "cld::policy::global::folder_and_asset_management::create_asset"
              name: "Upload assets"
              description: "Upload assets to any folder, including the root, without requiring specific folder permissions.
                Includes the option to select an upload preset and apply tags and metadata."
              scope_type: "prodenv"
              permission_type: "global"
              policy_statement: "permit(principal, action in [Cloudinary::Action::\"create\"], resource is Cloudinary::Asset);"
              category: "Management"
              sub_category: "Folder and asset management"
              created_at: 1719475215
              updated_at: 1719475215
          id: "upload_manager_12334565"
          name: "Upload manager"
          description: "Responsible for managing uploads and uploading new assets."
          management_type: "custom"
          permission_type: global
          scope_type: "prodenv"
          created_at: 1719475216
          updated_at: 1719475216
    # ------------------------------------
    GetRolePrincipalsExample:
      summary: Get a role's principals example
      value:
        data:
          - id: "1234abc"
            type: "user"
            role_id: "marketing_content_contributor_1357fhe"
            policy_parameters:
              folder_id: "asdfjkl12347890"
            scope_type: "prodenv"
            scope_id: "975l29lz02jt0836fhwi"
            created_at: 1719475216
            updated_at: 1719475216
          - id: "akwut728390anvy52sxgti"
            type: "apiKey"
            role_id: "marketing_content_contributor_1357fhe"
            policy_parameters:
              folder_id: "asdfjkl12347890"
            scope_type: "prodenv"
            scope_id: "975l29lz02jt0836fhwi"
            created_at: 1719475216
            updated_at: 1719475216
        # ------------------------------------
    GetRolePrincipalsWithParamKeyValueExample:
      summary: Get a role's principals with param_key and param_value for a specific content instance only.
      value:
        data:
          - id: "1234abc"
            type: "user"
            role_id: "marketing_content_contributor_1357fhe"
            policy_parameters:
              folder_id: "asdfjkl12347890"
            scope_type: "prodenv"
            scope_id: "975l29lz02jt0836fhwi"
            created_at: 1719475216
            updated_at: 1719475216
        # ------------------------------------
    GetPrincipalRolesExample:
      summary: Get a principal's roles example
      value:
        data:
          - id: "cld::role::account::reports"
            name: "Reports"
            description: "View account-level reports and usage metrics, including audit logs, dashboard usage summaries, and
              account-wide activity reports."
            management_type: "system"
            permission_type: "global"
            scope_type: "account"
            created_at: 1719475216
            updated_at: 1719475216
          - id: "upload_manager_12334565"
            name: "Upload manager"
            description: "Responsible for managing upload presets and uploading new assets."
            management_type: "custom"
            permission_type: "global"
            scope_type: "prodenv"
            scope_id: "975l29lz02jt0836fhwi"
            created_at: 1719475216
            updated_at: 1719475216
          - id: "marketing_content_contributor_1357fhe"
            name: "Marketing content contributor"
            description: "View all assets in selected folders and contribute to those folders, without permission to download."
            management_type: "custom"
            permission_type: "content"
            policy_parameters:
              folder_id: "asdfjkl12347890"
            scope_type: "prodenv"
            scope_id: "975l29lz02jt0836fhwi"
            created_at: 1719475215
            updated_at: 1719475215

    # ------------------------------------
    GetPrincipalRolesWithParamKeyValueExample:
      summary: Get a principal's roles with param_key and param_value for a specific content instance only.
      value:
        data:
          - id: "marketing_content_contributor_1357fhe"
            name: "Marketing content contributor"
            description: "View all assets in selected folders and contribute to those folders, without permission to download."
            management_type: "custom"
            permission_type: "content"
            scope_type: "prodenv"
            policy_parameters:
              folder_id: "asdfjkl12347890"
            created_at: 1719475215
            updated_at: 1719475215

    # ------------------------------------
    InspectExampleFolder:
      summary: |
        Inspect example: Retrieve all principals with roles for a specified folder
      value:
        data:
          principals:
            - type: "user"
              id: "1234abc"
              roles:
                - id: "marketing_content_contributor_1357fhe"
                  name: "Marketing content contributor"
                  description: "View all assets in selected folders and contribute to those folders, without permission to
                    download."
                  management_type: "custom"
                  permission_type: "content"
                  scope_type: "prodenv"
                  scope_id: "975l29lz02jt0836fhwi"
                  policy_parameters:
                    folder_id: "asdfjkl12347890"
                  created_at: 1719475215
                  updated_at: 1719475215
            - type: "user"
              id: "4567xyz"
              roles:
                - id: "campaign_organizer_351766dt"
                  name: "Campaign organizer"
                  description: "Share and download permissions on folders."
                  management_type: "custom"
                  permission_type: "content"
                  scope_type: "prodenv"
                  scope_id: "975l29lz02jt0836fhwi"
                  policy_parameters:
                    folder_id: "asdfjkl12347890"
                  created_at: 1719475215
                  updated_at: 1719475215

    # ------------------------------------
    InspectExampleAllFolders:
      summary: |
        Inspect example: Retrieve all principals with folder roles
      value:
        data:
          principals:
            - type: "user"
              id: "1234abc"
              roles:
                - id: "marketing_content_contributor_1357fhe"
                  name: "Marketing content contributor"
                  description: "View all assets in selected folders and contribute to those folders, without permission to
                    download."
                  management_type: "custom"
                  permission_type: "content"
                  scope_type: "prodenv"
                  scope_id: "975l29lz02jt0836fhwi"
                  policy_parameters:
                    folder_id: "asdfjkl12347890"
                  created_at: 1719475215
                  updated_at: 1719475215
            - type: "user"
              id: "4567xyz"
              roles:
                - id: "campaign_organizer_351766dt"
                  name: "Campaign organizer"
                  description: "View and download access to folders containing marketing campaign images and videos."
                  management_type: "custom"
                  permission_type: "content"
                  scope_type: "prodenv"
                  scope_id: "975l29lz02jt0836fhwi"
                  policy_parameters:
                    folder_id: "asdfjkl12347890"
                  created_at: 1719475215
                  updated_at: 1719475215
                - id: "website_admin_2523512"
                  name: "Website administrator"
                  description: "Manage assets delivered on the website."
                  management_type: "custom"
                  permission_type: "content"
                  scope_type: "prodenv"
                  scope_id: "975l29lz02jt0836fhwi"
                  policy_parameters:
                    folder_id: "bgxf992356125643"
                  created_at: 1719475215
                  updated_at: 1719475215

    # ------------------------------------
    InspectExampleProdEnv:
      summary: |
        Inspect example: Retrieve all principals with roles for a specific product environment
      value:
        data:
          principals:
            - type: "user"
              id: "1234abc"
              roles:
                - id: "marketing_content_contributor_1357fhe"
                  name: "Marketing content contributor"
                  description: "View all assets in selected folders and contribute to those folders, without permission to
                    download."
                  management_type: "custom"
                  permission_type: "content"
                  scope_type: "prodenv"
                  scope_id: "975l29lz02jt0836fhwi"
                  policy_parameters:
                    folder_id: "asdfjkl12347890"
                  created_at: 1719475215
                  updated_at: 1719475215
                - id: "manage_portals_238haspw"
                  name: "Brand portal manager"
                  description: "Manage the curation and sharing of brand portals."
                  management_type: "custom"
                  permission_type: "global"
                  scope_type: "prodenv"
                  scope_id: "975l29lz02jt0836fhwi"
                  created_at: 1719475215
                  updated_at: 1719475215
            - type: "apiKey"
              id: "a382ltieo893jhioqpg8urp"
              roles:
                - id: "upload_manager_351766dt"
                  name: "Manage upload settings"
                  description: "Manage settings related to upload management."
                  management_type: "custom"
                  permission_type: "global"
                  scope_type: "prodenv"
                  scope_id: "975l29lz02jt0836fhwi"
                  created_at: 1719475215
                  updated_at: 1719475215

    # ------------------------------------
    MissingFieldsErrorExample:
      summary: Missing fields
      value:
        error:
          category: "user_error"
          code: "ACCOUNTS_00005"
          message: "missing fields"
          details:
            fields:
              - name
    # ------------------------------------
    MissingPrincipalFieldsErrorExample:
      summary: Missing fields
      value:
        error:
          category: "user_error"
          code: "ACCOUNTS_00005"
          message: "missing fields"
          details:
            fields:
              - principal_type
      # ------------------------------------
    MissingRoleFieldsErrorExample:
      summary: Missing fields
      value:
        error:
          category: "user_error"
          code: "ACCOUNTS_00005"
          message: "missing fields"
          details:
            fields:
              - role_id
    # ------------------------------------
    InvalidFieldErrorExample:
      summary: Invalid field
      value:
        error:
          category: "user_error"
          code: "ACCOUNTS_00005"
          message: "invalid request"
          details:
            fields:
              - scope_type: "account"
    # ------------------------------------
    InvalidOperationFieldErrorExample:
      summary: Invalid field
      value:
        error:
          category: "user_error"
          code: "ACCOUNTS_00005"
          message: "invalid request"
          details:
            fields:
              - operation: "subtract"
    # ------------------------------------
    InvalidPolicyIDFieldErrorExample:
      summary: Invalid field
      value:
        error:
          category: "user_error"
          code: "ACCOUNTS_00005"
          message: "invalid request"
          details:
            fields:
              - system_policy_ids: "cld::global::upload_presets::sample"
    # ------------------------------------
    CedarErrorExample:
      summary: Invalid Cedar statement
      value:
        error:
          category: "user_error"
          code: "ACCOUNTS_00002"
          message: "invalid request"
          details:
            fields:
              - policy_statement: 'permit(principal == Cloudinary::APIKy::"1234", action == Cloudinary::Action::"read", resource
                  is Cloudinary::Folder ) when {resource.ancestor_ids.contains("asdfjkl12347890")} ;'
              - cedar_errors:
                  - cedar_message: "invalid_principal"
    # ------------------------------------
    AuthorizationErrorExample:
      summary: Authorization required
      value:
        error:
          category: "user_error"
          code: "ACCOUNTS_00006"
          message: "invalid credentials"
    # ------------------------------------
    ForbiddenErrorExample:
      summary: Not allowed
      value:
        error:
          category: "user_error"
          code: "ACCOUNTS_00006"
          message: "not allowed"
    # ------------------------------------
    CustomPolicyAlreadyExistsErrorExample:
      summary: Already exists for the scope
      value:
        error:
          category: "user_error"
          code: "ACCOUNTS_00006"
          message: "already exists for the scope"
          details:
            fields:
              - policy_statement: 'permit(principal == Cloudinary::APIKey::"1234", action == Cloudinary::Action::"read", resource
                  is Cloudinary::Folder ) when {resource.ancestor_ids.contains("asdfjkl12347890")} ;'
    # ------------------------------------
    RoleAlreadyExistsErrorExample:
      summary: Already exists
      value:
        error:
          category: "user_error"
          code: "ACCOUNTS_00006"
          message: "already exists"
          details:
            fields:
              - name: 'Admin'
    # ------------------------------------
    InternalServerErrorExample:
      summary: Internal server error
      value:
        error:
          category: "server_error"
          code: "ACCOUNTS_00001"
          message: "something went wrong"
    # ------------------------------------
    PolicyNotFoundErrorExample:
      summary: Policy not found
      value:
        error:
          category: "server_error"
          code: "ACCOUNTS_00003"
          message: "not found"
          details:
            fields:
              - policy_id: al18owlkth68901
    # ------------------------------------
    RoleNotFoundErrorExample:
      summary: Role not found
      value:
        error:
          category: "server_error"
          code: "ACCOUNTS_00003"
          message: "not found"
          details:
            fields:
              - role_id: manage_transformations_q1829qwnkli
    # ------------------------------------
    PrincipalNotFoundErrorExample:
      summary: Principal not found
      value:
        error:
          category: "server_error"
          code: "ACCOUNTS_00003"
          message: "not found"
          details:
            fields:
              - principal_id: xyz098ppb
    # ------------------------------------
    ScopeNotFoundErrorExample:
      summary: Scope not found
      value:
        error:
          category: "server_error"
          code: "ACCOUNTS_00003"
          message: "not found"
          details:
            fields:
              - scope_id: "55559999333hhx"
    # ------------------------------------
    ValidateCedarPolicyResponseExample:
      summary: Invalid Cedar policy
      value:
        valid: false
        errors:
          - cedar_message: "invalid_principal"
            cedar_code: "ACCOUNTS_00002"
    # ------------------------------------
    InspectMultipleRequestExample:
      summary: Role assignments for multiple principals
      value:
        scope_type: "prodenv"
        scope_id: "975l29lz02jt0836fhwi"
        principals:
          - type: "user"
            id: "1234abc"
          - type: "user"
            id: "4567xyz"
          - type: "apiKey"
            id: "a382ltieo893jhioqpg8urp"
        policy_parameters:
          folder_id: "asdfjkl12347890"
    # ------------------------------------
    InspectMultipleResponseExample:
      summary: Inspect multiple principals response
      value:
        data:
          principals:
            - type: "user"
              id: "1234abc"
              roles:
                - id: "marketing_content_contributor_1357fhe"
                  name: "Marketing content contributor"
                  description: "View all assets in selected folders and contribute to those folders, without permission to
                    download."
                  management_type: "custom"
                  permission_type: "content"
                  scope_type: "prodenv"
                  scope_id: "975l29lz02jt0836fhwi"
                  policy_parameters:
                    "folder_id": "asdfjkl12347890"
                  created_at: 1719475215
                  updated_at: 1719475215
            - type: "user"
              id: "4567xyz"
              roles:
                - id: "campaign_organizer_351766dt"
                  name: "Campaign organizer"
                  description: "Share and download permissions on folders."
                  management_type: "custom"
                  permission_type: "content"
                  scope_type: "prodenv"
                  scope_id: "975l29lz02jt0836fhwi"
                  policy_parameters:
                    folder_id: "<folder_id>"
                  created_at: 1719475215
                  updated_at: 1719475215
                - id: "cld::role::prodenv::reports"
                  name: "Reports"
                  description: "View product environment reports and usage metrics."
                  management_type: "system"
                  permission_type: "global"
                  scope_type: "prodenv"
                  scope_id: "975l29lz02jt0836fhwi"
                  created_at: 1719475216
                  updated_at: 1719475216
            - type: "apiKey"
              id: "a382ltieo893jhioqpg8urp"
              roles:
                - id: "upload_manager_351766dt"
                  name: "Upload manager"
                  description: "Responsible for managing upload presets and uploading new assets."
                  management_type: "custom"
                  permission_type: "global"
                  scope_type: "prodenv"
                  scope_id: "975l29lz02jt0836fhwi"
                  created_at: 1719475215
                  updated_at: 1719475215
x-speakeasy-globals:
  parameters:
    - $ref: '#/components/parameters/AccountIdParam'