Tyk Additional Permissions API

openapi: 3.2.0
info:
  contact:
    email: support@tyk.io
    name: Tyk Technologies
    url: https://tyk.io/contact
  description: '

    ## <a name="introduction"></a> Introduction


    The Tyk Dashboard API offers granular, programmatic access to a centralised database of resources that your Tyk nodes can pull from. This API has a dynamic user administrative structure which means the secret key that is used to communicate with your Tyk nodes can be kept secret and access to the wider management functions can be handled on a user-by-user and organisation-by-organisation basis.


    A common question around using a database-backed configuration is how to programmatically add API definitions to your Tyk nodes, the Dashboard API allows much more fine-grained, secure and multi-user access to your Tyk cluster, and should be used to manage a database-backed Tyk node.


    The Tyk Dashboard API works seamlessly with the Tyk Dashboard (and the two come bundled together).


    ## <a name="security-hierarchy"></a> Security Hierarchy


    The Dashboard API provides a more structured security layer to managing Tyk nodes.


    ### Organisations, APIs and Users


    With the Dashboard API and a database-backed Tyk setup, (and to an extent with file-based API setups - if diligence is used in naming and creating definitions), the following security model is applied to the management of Upstream APIs:


    * **Organisations**: All APIs are *owned* by an organisation, this is designated by the ''OrgID'' parameter in the API Definition.

    * **Users**: All users created in the Dashboard belong to an organisation (unless an exception is made for super-administrative access).

    * **APIs**: All APIs belong to an Organisation and only Users that belong to that organisation can see the analytics for those APIs and manage their configurations.

    * **API Keys**: API Keys are designated by organisation, this means an API key that has full access rights will not be allowed to access the APIs of another organisation on the same system, but can have full access to all APIs within the organisation.

    * **Access Rights**: Access rights are stored with the key, this enables a key to give access to multiple APIs, this is defined by the session object in the core Tyk API.


    In order to use the Dashboard API, you''ll need to get the ''Tyk Dashboard API Access Credentials'' secret from your user profile on the Dashboard UI.


    The secret you set should then be sent along as a header with each Dashboard API Request in order for it to be successful:



    authorization: <your-secret>

    '
  license:
    name: Mozilla Public License Version 2.0
    url: https://github.com/TykTechnologies/tyk/blob/master/LICENSE.md
  title: Tyk Dashboard Additional Permissions API
  version: 5.7.1
servers:
- url: https://{tenant}
  variables:
    tenant:
      default: localhost:8080
      description: Your dashboard host
security:
- bearerAuth: []
tags:
- description: "These APIs helps you get,add and delete (CRUD) a list of additional (custom) permissions for your Dashboard users. You can use the created additional permissions with Open Policy Agent (OPA). <br/>\n\n Once created, a custom permission will be added to standard list of user permissions. <br/>\n\nYou can also configure these custom permissions in the security.additional_permissions map in the Tyk Dashboard configuration file.\n\nYou can check the [full documentation here](https://tyk.io/docs/tyk-dashboard-api/org/permissions/).\n"
  externalDocs:
    description: Additional Permissions full documentation.
    url: https://tyk.io/docs/tyk-dashboard-api/org/permissions/
  name: Additional Permissions
paths:
  /api/org/permissions:
    get:
      description: This API returns by default the initial set of additional permissions defined in your Tyk Dashboard configuration, under `security.additional_permissions`. Once you update the permissions via the API, they will be stored at organisation level.
      operationId: listAdditionalPermissions
      responses:
        '200':
          content:
            application/json:
              example:
                additional_permissions:
                  api_developer: API Developer
                  api_manager: API Manager
              schema:
                $ref: '#/components/schemas/NewAdditionalPermissions'
          description: Additional Permissions retrieved successfully.
        '401':
          content:
            application/json:
              example:
                Message: Not authorised
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                Message: 'access denied: You do not have permission to access  /api/org/permissions'
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Forbidden
        '500':
          content:
            application/json:
              example:
                Message: Failed to marshal additional permissions.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Internal server error.
      summary: List additional permissions.
      tags:
      - Additional Permissions
    put:
      description: 'Whenever you want to add/update/delete an additional permission, just send back the updated list of permissions, through this PUT request to the API. For example if you initially had two additional permissions e.g ```{additional_permissions: {api_developer: API Developer, api_manager: API Manager}}``` to add a third permission called `custom_permission` you would append it to the original permission list and your request body would be: ```{additional_permissions: {api_developer: API Developer, api_manager: API Manager, custom_permission: Custom Permission}}```.'
      operationId: updateAdditionalPermissions
      requestBody:
        content:
          application/json:
            example:
              additional_permissions:
                api_developer: API Developer
                api_manager: API Manager
                custom_permission: Custom Permission
            schema:
              $ref: '#/components/schemas/NewAdditionalPermissions'
      responses:
        '200':
          content:
            application/json:
              example:
                Message: Additional Permissions updated in org level.
                Meta: null
                Status: OK
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Additional Permissions updated successfully.
        '400':
          content:
            application/json:
              example:
                Message: Failed to read response body.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Empty request body.
        '401':
          content:
            application/json:
              example:
                Message: Not authorised
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                Message: 'access denied: You do not have permission to access  /api/org/permissions'
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Forbidden
        '500':
          content:
            application/json:
              example:
                Message: Failed to unmarshal response body.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Invalid request body or failed to save permission.
      summary: Add/Delete/Update additional permission.
      tags:
      - Additional Permissions
components:
  schemas:
    NewAdditionalPermissions:
      properties:
        additional_permissions:
          additionalProperties:
            type: string
          example:
            api_developer: API Developer
            api_manager: API Manager
            custom_permission: Custom Permission
          type:
          - object
          - 'null'
      type: object
    ApiResponse:
      properties:
        ID:
          type: string
        Message:
          type: string
        Meta: {}
        Status:
          type: string
      type: object
  securitySchemes:
    bearerAuth:
      description: The Tyk Dashboard API Access Credentials
      scheme: bearer
      type: http