Tyk Policies API

openapi: 3.0.0
info:
  title: Tyk Dashboard Admin Additional Permissions Policies API
  version: 5.3.0
  description: 'For Tyk On-Premises installations only, the Dashboard Admin API has two endpoints and is used to set up and provision a Tyk Dashboard instance without the command line.


    In order to use the Dashboard Admin API, you''ll need to get the `admin_secret` value from your Tyk Dashboard configurations.


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


    ```

    admin-auth: <your-secret>

    ```'
servers:
- url: http://localhost/
- url: https://localhost/
security:
- ApiKeyAuth: []
tags:
- description: Policies are a template that enable you to create access rules, usage quota and rate limits that can be applied to multiple keys. They are a useful way to manage large groups of users, and to enforce quota changes on a global scale across any number of keys that are using a policy. When used in conjunction with the portal, developers that enroll for API access will be given a key that is attached to a specific policy. The policy settings are refreshed every time a key attempts access, meaning that updating a policy will have an effect across any keys that are attached to it.
  externalDocs:
    description: Security Policies Documentation.
    url: https://tyk.io/docs/basic-config-and-security/security/security-policies/
  name: Policies
paths:
  /api/portal/policies:
    get:
      description: Get list of policies. The result returned are paginated. Use the p query parameter to say which page you want returned. The default pagesize of the results is 10 but this can be changed in the dashboard config.
      operationId: getPolicies
      parameters:
      - description: Use p query parameter to say which page you want returned. Send number less than 0 to return all items.
        example: 1
        in: query
        name: p
        required: false
        schema:
          type: integer
      - description: Send any value in this query parameter to return only the active policies.
        example: 'true'
        in: query
        name: active
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                policiesExample:
                  $ref: '#/components/examples/policiesExample'
              schema:
                $ref: '#/components/schemas/ReturnDataStruct'
          description: List of all policies.
        '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/portal/policies'
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Returned if you do not have access to policies.
        '404':
          content:
            application/json:
              example:
                Message: Could not retrieve object list.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Not Found
        '500':
          content:
            application/json:
              example:
                Message: Failed to marshal data.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Internal server error.
      summary: Get list portal policies.
      tags:
      - Policies
    post:
      description: Creating policy definitions is slightly different to the core API, API definitions are wrapped inside an api_definition field and event handlers, such as webhooks are not embedded in the main api_definition object (though they can be), webhooks are instead appended as references into the hook_references field, the API will embed the correct webhook data into the event handler interface.
      operationId: postPolicies
      requestBody:
        content:
          application/json:
            example:
              access_rights:
                Itachi API:
                  allowed_urls:
                  - methods:
                    - GET
                    url: /users
                  api_id: 8ddd91f3cda9453442c477b06c4e2da4
                  api_name: Itachi API
                  disable_introspection: false
                  versions:
                  - Default
              active: true
              hmac_enabled: false
              is_inactive: false
              key_expires_in: 2592000
              max_query_depth: -1
              meta_data:
                email: itachi@tyk.io
                user_type: mobile_user
              name: Sample policy
              partitions:
                acl: true
                complexity: false
                per_api: false
                quota: true
                rate_limit: true
              per: 60
              quota_max: 10000
              quota_renewal_rate: 3600
              rate: 1000
              tags:
              - security
              throttle_interval: 10
              throttle_retry_limit: 10
            schema:
              $ref: '#/components/schemas/Policy'
      responses:
        '200':
          content:
            application/json:
              example:
                Message: 663b4bbd5715ec323b424dca
                Meta: null
                Status: OK
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Policy created.
        '400':
          content:
            application/json:
              example:
                Message: This policy name has already been used. Enter a unique policy name.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Returned when the policy body fails validation.
        '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: Request body malformed.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Returned when you send a malformed request body or when you don't have permission to add this object.
        '500':
          content:
            application/json:
              example:
                Message: Failure creating data, please contact your administrator.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Internal server error.
      summary: Create policy definition.
      tags:
      - Policies
  /api/portal/policies/{id}:
    delete:
      description: Delete a Policy by ID.
      operationId: deletePolicy
      parameters:
      - description: ID of policy to delete.
        example: 66570989d98dd00001da17f1
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                Message: Data deleted
                Meta: null
                Status: OK
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Deleted policy successfully.
        '400':
          content:
            application/json:
              example:
                Message: Invalid policy ID.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Returned when you send a policy ID that is invalid.
        '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/portal/policies/{id}'
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Returned if you do not have access to policies.
        '404':
          content:
            application/json:
              example:
                Message: Could not retrieve object for deletion
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Returned if policy with specified ID does not exist.
        '500':
          content:
            application/json:
              example:
                Message: Failure deleting data, please contact your administrator.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Internal server error.
      summary: Delete a single policy by ID.
      tags:
      - Policies
    get:
      description: Get a policy by ID.
      operationId: getPolicy
      parameters:
      - description: ID of policy to get.
        example: 66570989d98dd00001da17f1
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                access_rights:
                  Itachi API:
                    allowed_urls:
                    - methods:
                      - GET
                      url: /users
                    api_id: 8ddd91f3cda9453442c477b06c4e2da4
                    api_name: Itachi API
                    disable_introspection: false
                    versions:
                    - Default
                active: true
                hmac_enabled: false
                is_inactive: false
                key_expires_in: 2592000
                max_query_depth: -1
                meta_data:
                  email: itachi@tyk.io
                  user_type: mobile_user
                name: Sample policy
                partitions:
                  acl: true
                  complexity: false
                  per_api: false
                  quota: true
                  rate_limit: true
                per: 60
                quota_max: 10000
                quota_renewal_rate: 3600
                rate: 1000
                tags:
                - security
                throttle_interval: 10
                throttle_retry_limit: 10
              schema:
                $ref: '#/components/schemas/Policy'
          description: Policy fetched.
        '400':
          content:
            application/json:
              example:
                Message: Invalid policy ID.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Returned when you send a policy ID that is invalid.
        '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/portal/policies/{id}'
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              example:
                Message: Could not retrieve portal object.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Policy with the given ID was not found.
        '500':
          content:
            application/json:
              example:
                Message: Failure creating data, please contact your administrator.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Internal server error.
      summary: Get a single policy by ID.
      tags:
      - Policies
    put:
      description: Update a policy definition.
      operationId: putPolicies
      parameters:
      - description: ID of policy to update.
        example: 66570989d98dd00001da17f1
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              access_rights:
                Itachi API:
                  allowed_urls:
                  - methods:
                    - GET
                    url: /users
                  api_id: 8ddd91f3cda9453442c477b06c4e2da4
                  api_name: Itachi API
                  disable_introspection: false
                  versions:
                  - Default
              active: true
              hmac_enabled: false
              is_inactive: false
              key_expires_in: 2592000
              max_query_depth: -1
              meta_data:
                email: itachi@tyk.io
                user_type: mobile_user
              name: Sample policy
              partitions:
                acl: true
                complexity: false
                per_api: false
                quota: true
                rate_limit: true
              per: 60
              quota_max: 10000
              quota_renewal_rate: 3600
              rate: 1000
              tags:
              - security
              - messages
              throttle_interval: 10
              throttle_retry_limit: 10
            schema:
              $ref: '#/components/schemas/Policy'
      responses:
        '200':
          content:
            application/json:
              example:
                Message: Data updated
                Meta: null
                Status: OK
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Policy updated.
        '400':
          content:
            application/json:
              example:
                Message: Invalid policy ID.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Returned when you send an invalid ID or when the policy body fails validation.
        '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: Request body malformed.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Returned when you send a malformed request body or when you don't have permission to update this object.
        '404':
          content:
            application/json:
              example:
                Message: Could not retrieve portal object.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Returned if policy with specified ID does not exist.
        '500':
          content:
            application/json:
              example:
                Message: Failure saving data, please contact your administrator.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Internal server error.
      summary: Update policy definition.
      tags:
      - Policies
  /api/portal/policies/search:
    get:
      description: Search list of policies. If query parameter q is a policy ID it will look for policies that have the given ID. However if q is not a policy ID it will return policies with whose name matches the patten based via q query parameter. If you send a policy ID in query parameter q and also send query parameter policy_ids,only policy_ids will be used for searching.
      operationId: searchPolicies
      parameters:
      - description: Search for policy using policy ID or name.
        example: 5eb6349543f0440001373f5c
        in: query
        name: q
        required: false
        schema:
          type: string
      - description: A list of comma separated policy IDs that you want to search for.
        example: 5eb6349543f0440001373f5c,5ead7120575961000181867e
        in: query
        name: policy_ids
        required: false
        schema:
          type: string
      - description: Send any value in this query parameter to return only the active policies.
        example: 'true'
        in: query
        name: active
        required: false
        schema:
          type: string
      - description: Return policies whose state field matches the sent value e.g if you send state as deny policies returned are those whose state filed value is set as deny.
        example: deny
        in: query
        name: state
        required: false
        schema:
          enum:
          - deny
          - active
          - draft
          type: string
      - description: Field you want to use to sort the returned policies.
        example: name
        in: query
        name: sort
        required: false
        schema:
          enum:
          - date_created
          - name
          - state
          type: string
      - description: Comma separate list of API IDs. Return only policy that that have the given API IDs in their access_right.
        example: 5963f8fdedee405143f5858ea17de422
        in: query
        name: api_id
        required: false
        schema:
          type: string
      - description: Return policy whose auth_type field has the given value.
        example: authToken
        in: query
        name: auth_type
        required: false
        schema:
          type: string
      - description: Use p query parameter to say which page you want returned. Send number less than 0 to return all items.
        example: 1
        in: query
        name: p
        required: false
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              examples:
                policiesExample:
                  $ref: '#/components/examples/policiesExample'
              schema:
                $ref: '#/components/schemas/ReturnDataStruct'
          description: List of policies.
        '400':
          content:
            application/json:
              example:
                Message: Policy ID is not in hex format.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Returned when you send policy IDs that are not in hexadecimal format.
        '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/portal/policies/search'
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              example:
                Message: Could not retrieve policies.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Not Found
        '500':
          content:
            application/json:
              example:
                Message: Failed to marshal data
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Internal server error.
      summary: Search list of policies.
      tags:
      - Policies
  /tyk/policies:
    get:
      description: Retrieve all the policies in your Tyk instance. Returns an array policies.
      operationId: listPolicies
      responses:
        '200':
          content:
            application/json:
              examples:
                policiesExample:
                  $ref: '#/components/examples/policiesExample_2'
              schema:
                items:
                  $ref: '#/components/schemas/Policy_2'
                type: array
          description: List of all policies.
        '403':
          content:
            application/json:
              example:
                message: Attempted administrative access with invalid or missing key!
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Forbidden
      summary: Tyk List Policies.
      tags:
      - Policies
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      description: Create a policy in your Tyk Instance.
      operationId: addPolicy
      requestBody:
        content:
          application/json:
            example:
              access_rights:
                itachi-api:
                  allowed_urls:
                  - methods:
                    - GET
                    url: /users
                  api_id: 8ddd91f3cda9453442c477b06c4e2da4
                  api_name: Itachi api
                  disable_introspection: false
                  versions:
                  - Default
              active: true
              hmac_enabled: false
              id: 5ead7120575961000181867e
              is_inactive: false
              key_expires_in: 2592000
              max_query_depth: -1
              meta_data:
                update: sample policy update
                user_type: mobile_user
              name: Sample policy
              partitions:
                acl: true
                complexity: false
                per_api: false
                quota: true
                rate_limit: true
              per: 60
              quota_max: 10000
              quota_renewal_rate: 3600
              rate: 1000
              tags:
              - security
              throttle_interval: 10
              throttle_retry_limit: 10
            schema:
              $ref: '#/components/schemas/Policy_2'
      responses:
        '200':
          content:
            application/json:
              example:
                action: added
                key: 5ead7120575961000181867e
                status: ok
              schema:
                $ref: '#/components/schemas/ApiModifyKeySuccess'
          description: Policy created.
        '400':
          content:
            application/json:
              example:
                message: Request malformed
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Malformed request.
        '403':
          content:
            application/json:
              example:
                message: Attempted administrative access with invalid or missing key!
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Forbidden
        '500':
          content:
            application/json:
              example:
                message: Due to enabled service policy source, please use the Dashboard API.
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Internal server error.
      summary: Tyk Create a Policy.
      tags:
      - Policies
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /tyk/policies/{polID}:
    delete:
      description: Delete a policy by ID in your Tyk instance.
      operationId: deletePolicy
      parameters:
      - description: You can retrieve details of a single policy by ID in your Tyk instance.
        example: 5ead7120575961000181867e
        in: path
        name: polID
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                action: deleted
                key: 5ead7120575961000181867e
                status: ok
              schema:
                $ref: '#/components/schemas/ApiModifyKeySuccess'
          description: Deleted policy by ID
        '400':
          content:
            application/json:
              example:
                message: Must specify an apiID to update
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Policy Id not provided
        '403':
          content:
            application/json:
              example:
                message: Attempted administrative access with invalid or missing key!
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Forbidden
        '500':
          content:
            application/json:
              example:
                message: Delete failed
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Internal server error.
      summary: Tyk Delete a Policy.
      tags:
      - Policies
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      description: You can retrieve details of a single policy by ID in your Tyk instance.
      operationId: getPolicy
      parameters:
      - description: You can retrieve details of a single policy by ID in your Tyk instance.
        example: 5ead7120575961000181867e
        in: path
        name: polID
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                access_rights:
                  itachi-api:
                    allowed_urls:
                    - methods:
                      - GET
                      url: /users
                    api_id: 8ddd91f3cda9453442c477b06c4e2da4
                    api_name: Itachi api
                    disable_introspection: false
                    versions:
                    - Default
                active: true
                hmac_enabled: false
                id: 5ead7120575961000181867e
                is_inactive: false
                key_expires_in: 2592000
                max_query_depth: -1
                meta_data:
                  update: sample policy update
                  user_type: mobile_user
                name: Sample policy
                partitions:
                  acl: true
                  complexity: false
                  per_api: false
                  quota: true
                  rate_limit: true
                per: 60
                quota_max: 10000
                quota_renewal_rate: 3600
                rate: 1000
                tags:
                - security
                throttle_interval: 10
                throttle_retry_limit: 10
              schema:
                $ref: '#/components/schemas/Policy_2'
          description: Get details of a single policy.
        '403':
          content:
            application/json:
              example:
                message: Attempted administrative access with invalid or missing key!
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Forbidden
        '404':
          content:
            application/json:
              example:
                message: Policy not found
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Policy not found
      summary: Tyk Get a Policy.
      tags:
      - Policies
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      description: You can update a Policy in your Tyk Instance by ID.
      operationId: updatePolicy
      parameters:
      - description: You can retrieve details of a single policy by ID in your Tyk instance.
        example: 5ead7120575961000181867e
        in: path
        name: polID
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              access_rights:
                itachi-api:
                  allowed_urls:
                  - methods:
                    - GET
                    url: /users
                  api_id: 8ddd91f3cda9453442c477b06c4e2da4
                  api_name: Itachi api
                  disable_introspection: false
                  versions:
                  - Default
              active: true
              hmac_enabled: false
              id: 5ead7120575961000181867e
              is_inactive: false
              key_expires_in: 2592000
              max_query_depth: -1
              meta_data:
                update: sample policy update
                user_type: mobile_user
              name: update policy sample
              partitions:
                acl: true
                complexity: false
                per_api: false
                quota: true
                rate_limit: true
              per: 60
              quota_max: 10000
              quota_renewal_rate: 3600
              rate: 1000
              tags:
              - security
              throttle_interval: 10
              throttle_retry_limit: 10
            schema:
              $ref: '#/components/schemas/Policy_2'
      responses:
        '200':
          content:
            application/json:
              example:
                action: modified
                key: 5ead7120575961000181867e
                status: ok
              schema:
                $ref: '#/components/schemas/ApiModifyKeySuccess'
          description: Policy updated
        '400':
          content:
            application/json:
              example:
                message: Request malformed
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: malformed request
        '403':
          content:
            application/json:
              example:
                message: Attempted administrative access with invalid or missing key!
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Forbidden
        '500':
          content:
            application/json:
              example:
                message: Failed to create file!
                status: error
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Internal server error.
      sum

# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tyk/refs/heads/main/openapi/tyk-policies-api-openapi.yml