Aiven Permissions API

openapi: 3.2.0
info:
  contact:
    email: support@aiven.io
    name: Aiven support team
    url: https://aiven.io/support-services
  title: Aiven API Documentation Permissions API
  version: v1
  x-logo:
    altText: Aiven logo
    backgroundColor: '#fafafa'
    href: https://api.aiven.io/doc
    url: https://aiven.io/assets/img/aiven-logo.png
  description: '# Introduction


    Direct link to openapi.json for use with external tools


    Aiven is a modern fully-managed open source data platform for streaming, storing, and analyzing data on any public cloud.'
servers:
- url: https://api.aiven.io/v1
tags:
- name: Permissions
  x-displayName: Permissions
paths:
  /organization/{organization_id}/permissions/{resource_type}/{resource_id}:
    get:
      summary: List of permissions
      tags:
      - Permissions
      operationId: PermissionsGet
      description: Returns a list of permissions for a resource.
      parameters:
      - $ref: '#/components/parameters/organization_id'
      - $ref: '#/components/parameters/resource_type'
      - $ref: '#/components/parameters/resource_id'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionsGetResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    title: Human readable error message
                  errors:
                    type: array
                    title: List of error details. Typically there is only one element
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                          title: Human readable error message
                        error_code:
                          type: string
                          enum:
                          - unsupported_resource_type
                          title: Machine processable error code. Clients must be prepared to handle new codes.
                          description: 'unsupported_resource_type: The resource type is not supported for the current operation'
      security:
      - tokenAuth: []
        oauth2:
        - accounts:read
        - authentication:read
    put:
      summary: Set permissions
      tags:
      - Permissions
      operationId: PermissionsSet
      description: Replaces permissions for a resource. The entries entry provided in the request body are applied, replacing all the previously defined permissions defined on the specified resource. Updates are not atomic (changes are computed and each are individually applied); if an error occurs, permissions may have been partially updated. They are however idempotent, so in case of transient errors it is possible to simply retry the request.
      parameters:
      - $ref: '#/components/parameters/organization_id'
      - $ref: '#/components/parameters/resource_type'
      - $ref: '#/components/parameters/resource_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PermissionsSetRequestBody'
            example:
              permissions:
              - permissions:
                - read_only
                principal_id: u12345
                principal_type: user
      responses:
        '204':
          description: Set permissions
          content: {}
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    title: Human readable error message
                  errors:
                    type: array
                    title: List of error details. Typically there is only one element
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                          title: Human readable error message
                        error_code:
                          type: string
                          enum:
                          - unsupported_resource_type
                          title: Machine processable error code. Clients must be prepared to handle new codes.
                          description: 'unsupported_resource_type: The resource type is not supported for the current operation'
      security:
      - tokenAuth: []
        oauth2:
        - accounts:write
        - authentication:write
    patch:
      summary: Update permissions
      tags:
      - Permissions
      operationId: PermissionsUpdate
      description: Updates permissions for a resource. Each entry provided in the request body is applied, replacing the previous assignment for the target principal. To remove permission assignments an entry with an empty set of permissions must be provided. Updates are not atomic (each entry is individually applied); if an error occurs, permissions may have been partially updated. They are however idempotent, so in case of transient errors it is possible to simply retry the request.
      parameters:
      - $ref: '#/components/parameters/organization_id'
      - $ref: '#/components/parameters/resource_type'
      - $ref: '#/components/parameters/resource_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PermissionsUpdateRequestBody'
            example:
              operation: set
              permissions:
              - permissions:
                - read_only
                principal_id: u12345
                principal_type: user
      responses:
        '204':
          description: Update permissions
          content: {}
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    title: Human readable error message
                  errors:
                    type: array
                    title: List of error details. Typically there is only one element
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                          title: Human readable error message
                        error_code:
                          type: string
                          enum:
                          - unsupported_resource_type
                          title: Machine processable error code. Clients must be prepared to handle new codes.
                          description: 'unsupported_resource_type: The resource type is not supported for the current operation'
      security:
      - tokenAuth: []
        oauth2:
        - accounts:write
        - authentication:write
components:
  parameters:
    resource_type:
      in: path
      name: resource_type
      description: Resource type
      schema:
        type: string
        enum:
        - project
        - organization
        - organization_unit
      required: true
    resource_id:
      in: path
      name: resource_id
      description: Resource Id
      schema:
        type: string
      required: true
    organization_id:
      in: path
      name: organization_id
      description: ID of an organization
      schema:
        type: string
      required: true
  schemas:
    PermissionsUpdateRequestBody:
      type: object
      description: PermissionsUpdateRequestBody
      properties:
        operation:
          type: string
          description: An enumeration.
          title: Operation to perform
          default: set
          enum:
          - grant
          - set
          - revoke
        permissions:
          type: array
          description: List of roles to adjust
          items:
            type: object
            properties:
              permissions:
                type: array
                description: List of roles
                items:
                  type: string
              principal_id:
                type: string
                description: ID of the principal
              principal_type:
                type: string
                description: An enumeration.
                title: Type of the principal
                enum:
                - user
                - user_group
            required:
            - permissions
            - principal_id
            - principal_type
      required:
      - permissions
    PermissionsSetRequestBody:
      type: object
      description: PermissionsSetRequestBody
      properties:
        permissions:
          type: array
          description: List of roles to set
          items:
            type: object
            properties:
              permissions:
                type: array
                description: List of roles
                items:
                  type: string
              principal_id:
                type: string
                description: ID of the principal
              principal_type:
                type: string
                description: An enumeration.
                title: Type of the principal
                enum:
                - user
                - user_group
            required:
            - permissions
            - principal_id
            - principal_type
      required:
      - permissions
    PermissionsGetResponse:
      type: object
      description: PermissionsGetResponse
      properties:
        permissions:
          type: array
          description: List of roles
          items:
            type: object
            properties:
              create_time:
                type: string
                maxLength: 36
                description: Create Time
              permissions:
                type: array
                description: List of roles
                items:
                  type: string
              principal_id:
                type: string
                description: ID of the principal
              principal_type:
                type: string
                description: An enumeration.
                title: Type of the principal
                enum:
                - user
                - user_group
              update_time:
                type: string
                maxLength: 36
                description: Update Time
            required:
            - create_time
            - permissions
            - principal_id
            - principal_type
            - update_time
      required:
      - permissions
  securitySchemes:
    tokenAuth:
      description: 'Header should be of the format `authorization: aivenv1 <TOKEN>`. Tokens can be obtained from [your Aiven profile page](https://console.aiven.io/profile/auth)'
      scheme: bearer
      type: http
    oauth2:
      type: oauth2
      description: OAuth2 security scheme
      flows:
        authorizationCode:
          authorizationUrl: https://console.aiven.io/oauth/authorize
          tokenUrl: https://api.aiven.io/v1/oauth2/token
          scopes:
            all: Provide full access to the API
            accounts: Allow enumerating and reading accounts configuration
            accounts:read: Allow modifying account configuration
            accounts:write: Provides full access to authentication related API
            authentication: Provides full access to authentication related API
            authentication:read: Allow reading authentication related configuration on resources (user profile, accounts)
            authentication:write: Allow modifying authentication related configurations on resources (user profile, accounts)
            billing: Provide full access to billing APIs
            billing:read: Allow reading billing information and configuration
            billing:write: Allow writing billing configuration
            payments: Provide full access to payment method APIs
            payments:read: Allow reading the payment method configurations
            payments:write: Allows writing payment method configuration
            privatelink: Provide full access to private link APIs
            privatelink:read: Allow enumerating and reading private link items and configurations
            privatelink:write: Allow writing (creating, modifying, deleting) private link items
            projects: Provide full access to projects APIs
            projects:read: Allow enumerating projects and reading their configuration
            projects:write: Allow writing (creating, modifying, deleting) projects
            scim: Provide full access to SCIM operations
            scim:read: Allow reading SCIM endpoints
            scim:write: Allow writing (modifying) SCIM endpoints
            services: Provide full access to services APIs
            services:read: Allow enumerating services and reading their configuration
            services:write: Allow writing (creating, modifying, deleting) services
            static_ips: Provide full access to static IPs APIs
            static_ips:read: Allow enumerating and reading static IP items and configurations
            static_ips:write: Allow writing (creating, modifying, deleting) static IP items
            tickets: Provide full access to support ticket APIs
            tickets:read: Allow enumerating and reading support tickets
            tickets:write: Allow writing (creating, modifying) support tickets
            user: Provide full access to user profile APIs
            user:read: Allow reading user profile and configuration
            user:write: Allow writing (modifying) user profile and configuration
externalDocs:
  description: Aiven CLI client
  url: https://github.com/aiven/aiven-client