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. On Aiven Platform, you can operate your data infrastructure with a few devops tools: Aiven Console, Aiven Terraform Provider, Aiven CLI, and Aiven Operator for Kubernetes. All of them are built on an open secure powerful REST API for integration with custom tooling. The Aiven REST API

    provides programmatic access to Aiven.io services. To call the Aiven API, you can use either CLI tools (for example, `cURL` or Aiven CLI client) or GUI tools, such as the Aiven public API Postman collection. This Aiven API documentation will help you operate your Aiven organization, projects, or services programmatically by integrating your applications and processes with Aiven. # Description


    Aiven''s APIs (Application Programming Interfaces) power its platform for data management. Aiven has a number of REST APIs that can help you build strong and robust data infrastructure for your applications. The Aiven API is organized around core resources. Each core resource has multiple endpoints, which can be interacted with using different HTTP methods. ## Core resources


    ### Platform APIs


    Account

    Operations on the organization level related to accounts, projects, user groups, users, invites, billing groups, payment methods, credit cards, authentication methods, and more

    User

    Operations related to users and users'' profiles, access, authentication, authorization, user management, and more

    Project

    General operations on projects related to users, VPCs, invitations, alerts, peering connections, and more

    BillingGroup

    Operation on invoices, billing groups'' credits and events

    Support ticket

    Operations on support tickets: listing, creating, looping users in


    ### Services APIs


    Service

    All general (non-service-specific) operations on the service level: service creation, termination, configuration, updates, information retrieval, reset, and more

    Service Integrations

    Operations related to integrating services and managing service integrations

    Service: ClickHouse

    ClickHouse-specific operations on queries and databases

    Service: Flink

    Operations on Flink queries, jobs, and applications

    Service: Kafka

    Kafka and Kafka Connect specific operations on connectors, ACL entries, quotas, topics, topic messages, schema registry, and more

    Service: Kafka MirrorMaker

    Operations on replication flows

    Service: MySQL

    Fetching service query statistics

    Service: OpenSearch

    Operations on ACL configuration, security administration and configuration

    Service: PostgreSQL

    Operations on extensions, service query statistics, and connection pools


    # Requests


    There are multiple ways you can interact with the Aiven API over HTTP. You can access it by sending requests from a client (for example, a web browser) to the Aiven''s server. In this API reference, you''ll find code examples of how to do that using `cURL` and a few different client libraries (programming languages). To send an API request, you need to specify the following:


    * HTTP method

    * Path

    * Request headers


    Typically, `content-type` needs to be set to `application/json`: `content-type: application/json`. There are a few exceptions though. * Path, query, or body parameters (either required or optional).'
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_id:
      in: path
      name: resource_id
      description: Resource Id
      schema:
        type: string
      required: true
    resource_type:
      in: path
      name: resource_type
      description: Resource type
      schema:
        type: string
        enum:
        - project
        - organization
        - organization_unit
      required: true
    organization_id:
      in: path
      name: organization_id
      description: ID of an organization
      schema:
        type: string
      required: true
  schemas:
    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
    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
  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
            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
x-provenance:
  method: harvested
  publisher: Aiven
  source: https://api.aiven.io/doc/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)