openapi: 3.0.0
info:
  title: Azure API Management - Subscriptions
  description: Use these REST APIs for performing operations on Subscription entity
    associated with your Azure API Management deployment. The Subscription
    entity represents the association between a user and a product in API
    Management. Products contain one or more APIs, and once a product is
    published, developers can subscribe to the product and begin to use the
    product’s APIs.
  version: 2017-03-01
security:
  - apim_key: []
paths:
  /subscriptions:
    get:
      tags:
        - Subscriptions
      operationId: Subscription_List
      description: Lists all subscriptions of the API Management service instance.
      parameters:
        - name: $filter
          in: query
          required: false
          description: >-
            | Field        | Supported operators    | Supported
            functions                         |

            |--------------|------------------------|---------------------------------------------|

            | id           | ge, le, eq, ne, gt, lt | substringof, contains, startswith, endswith |

            | name         | ge, le, eq, ne, gt, lt | substringof, contains, startswith, endswith |

            | stateComment | ge, le, eq, ne, gt, lt | substringof, contains, startswith, endswith |

            | userId       | ge, le, eq, ne, gt, lt | substringof, contains, startswith, endswith |

            | productId    | ge, le, eq, ne, gt, lt | substringof, contains, startswith, endswith |

            | state        | eq                     |                                             |
          schema:
            type: string
        - $ref: ./apimanagement.json#/components/parameters/TopQueryParameter
        - $ref: ./apimanagement.json#/components/parameters/SkipQueryParameter
        - $ref: ./apimanagement.json#/components/parameters/ApiVersionParameter
      responses:
        "200":
          description: A collection of the Subscription entities for the specified API
            Management service instance.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriptionCollection"
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: ./apimanagement.json#/definitions/ErrorResponse
      x-ms-pageable:
        nextLinkName: nextLink
      x-ms-odata: "#/components/schemas/SubscriptionContract"
  "/subscriptions/{sid}":
    get:
      tags:
        - Subscriptions
      operationId: Subscription_Get
      description: Gets the specified Subscription entity.
      parameters:
        - $ref: "#/components/parameters/SubscriptionEntityIdParameter"
        - $ref: ./apimanagement.json#/components/parameters/ApiVersionParameter
      responses:
        "200":
          description: The response body contains the specified Subscription entity.
          headers:
            ETag:
              description: Current entity state version. Should be treated as opaque and
                used to make conditional HTTP requests.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriptionContract"
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: ./apimanagement.json#/definitions/ErrorResponse
    put:
      tags:
        - Subscriptions
      operationId: Subscription_CreateOrUpdate
      description: Creates or updates the subscription of specified user to the specified
        product.
      parameters:
        - $ref: "#/components/parameters/SubscriptionEntityIdParameter"
        - name: notify
          in: query
          required: false
          description: Notify the subscriber of the subscription state change to Submitted
            or Active state.
          schema:
            type: string
            enum:
              - "False"
              - "True"
            default: "False"
        - $ref: ./apimanagement.json#/components/parameters/ApiVersionParameter
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SubscriptionCreateParameters"
        description: Create parameters.
        required: true
      responses:
        "200":
          description: The user already subscribed to the product.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriptionContract"
        "201":
          description: The user was successfully subscribed to the product.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriptionContract"
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: ./apimanagement.json#/definitions/ErrorResponse
    patch:
      tags:
        - Subscriptions
      operationId: Subscription_Update
      description: Updates the details of a subscription specified by its identifier.
      parameters:
        - $ref: "#/components/parameters/SubscriptionEntityIdParameter"
        - name: If-Match
          in: header
          required: true
          description: ETag of the Subscription Entity. ETag should match the current
            entity state from the header response of the GET request or it
            should be * for unconditional update.
          schema:
            type: string
        - name: notify
          in: query
          required: false
          description: Notify the subscriber of the subscription state change to Submitted
            or Active state.
          schema:
            type: string
            enum:
              - "False"
              - "True"
            default: "False"
        - $ref: ./apimanagement.json#/components/parameters/ApiVersionParameter
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SubscriptionUpdateParameters"
        description: Update parameters.
        required: true
      responses:
        "204":
          description: The subscription details were successfully updated.
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: ./apimanagement.json#/definitions/ErrorResponse
    delete:
      tags:
        - Subscriptions
      operationId: Subscription_Delete
      description: Deletes the specified subscription.
      parameters:
        - $ref: "#/components/parameters/SubscriptionEntityIdParameter"
        - name: If-Match
          in: header
          required: true
          description: ETag of the Subscription Entity. ETag should match the current
            entity state from the header response of the GET request or it
            should be * for unconditional update.
          schema:
            type: string
        - $ref: ./apimanagement.json#/components/parameters/ApiVersionParameter
      responses:
        "204":
          description: The subscription details were successfully deleted.
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: ./apimanagement.json#/definitions/ErrorResponse
  "/subscriptions/{sid}/regeneratePrimaryKey":
    post:
      tags:
        - Subscriptions
      operationId: Subscription_RegeneratePrimaryKey
      description: Regenerates primary key of existing subscription of the API Management
        service instance.
      parameters:
        - $ref: "#/components/parameters/SubscriptionEntityIdParameter"
        - $ref: ./apimanagement.json#/components/parameters/ApiVersionParameter
      responses:
        "204":
          description: The primary key was successfully regenerated.
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: ./apimanagement.json#/definitions/ErrorResponse
  "/subscriptions/{sid}/regenerateSecondaryKey":
    post:
      tags:
        - Subscriptions
      operationId: Subscription_RegenerateSecondaryKey
      description: Regenerates secondary key of existing subscription of the API Management
        service instance.
      parameters:
        - $ref: "#/components/parameters/SubscriptionEntityIdParameter"
        - $ref: ./apimanagement.json#/components/parameters/ApiVersionParameter
      responses:
        "204":
          description: The secondary key was successfully regenerated.
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: ./apimanagement.json#/definitions/ErrorResponse
servers:
  - url: "{apimBaseUrl}"
    variables:
      apimBaseUrl:
        description: The management endpoint of the API Management service, for example
          https://myapimservice.management.azure-api.net.
        x-ms-skip-url-encoding: true
        default: ""
components:
  parameters:
    SubscriptionEntityIdParameter:
      name: sid
      in: path
      required: true
      description: Subscription entity Identifier. The entity represents the association
        between a user and a product in API Management.
      x-ms-parameter-location: method
      schema:
        type: string
        maxLength: 256
        pattern: ^[^*#&+:<>?]+$
  securitySchemes:
    apim_key:
      type: apiKey
      name: Authorization
      in: header
  schemas:
    SubscriptionCollection:
      properties:
        value:
          type: array
          items:
            $ref: "#/components/schemas/SubscriptionContract"
          description: Page values.
        count:
          type: integer
          description: Total number of entities
        nextLink:
          type: string
          description: Next page link if any.
      description: Paged Subscriptions list representation.
    SubscriptionContract:
      properties:
        id:
          type: string
          description: Identifier of the Subscription.
      allOf:
        - $ref: "#/components/schemas/SubscriptionContractProperties"
      description: Subscription details.
    SubscriptionContractProperties:
      properties:
        userId:
          type: string
          description: The user resource identifier of the subscription owner. The value is
            a valid relative URL in the format of /users/{uid} where {uid} is a
            user identifier.
        productId:
          type: string
          description: The product resource identifier of the subscribed product. The value
            is a valid relative URL in the format of /products/{productId} where
            {productId} is a product identifier.
        name:
          type: string
          description: The name of the subscription, or null if the subscription has no
            name.
          minLength: 0
          maxLength: 100
        state:
          type: string
          description: Subscription state. Possible states are * active – the subscription
            is active, * suspended – the subscription is blocked, and the
            subscriber cannot call any APIs of the product, * submitted – the
            subscription request has been made by the developer, but has not yet
            been approved or rejected, * rejected – the subscription request has
            been denied by an administrator, * cancelled – the subscription has
            been cancelled by the developer or administrator, * expired – the
            subscription reached its expiration date and was deactivated.
          enum:
            - suspended
            - active
            - expired
            - submitted
            - rejected
            - cancelled
          x-ms-enum:
            name: SubscriptionState
            modelAsString: false
        createdDate:
          type: string
          format: date-time
          description: >
            Subscription creation date. The date conforms to the following
            format: `yyyy-MM-ddTHH:mm:ssZ` as specified by the ISO 8601
            standard.
          readOnly: true
        startDate:
          type: string
          format: date-time
          description: >
            Subscription activation date. The setting is for audit purposes only
            and the subscription is not automatically activated. The
            subscription lifecycle can be managed by using the `state` property.
            The date conforms to the following format: `yyyy-MM-ddTHH:mm:ssZ` as
            specified by the ISO 8601 standard.
        expirationDate:
          type: string
          format: date-time
          description: >
            Subscription expiration date. The setting is for audit purposes only
            and the subscription is not automatically expired. The subscription
            lifecycle can be managed by using the `state` property. The date
            conforms to the following format: `yyyy-MM-ddTHH:mm:ssZ` as
            specified by the ISO 8601 standard.
        endDate:
          type: string
          format: date-time
          description: >
            Date when subscription was cancelled or expired. The setting is for
            audit purposes only and the subscription is not automatically
            cancelled. The subscription lifecycle can be managed by using the
            `state` property. The date conforms to the following format:
            `yyyy-MM-ddTHH:mm:ssZ` as specified by the ISO 8601 standard.
        notificationDate:
          type: string
          format: date-time
          description: >
            Upcoming subscription expiration notification date. The date
            conforms to the following format: `yyyy-MM-ddTHH:mm:ssZ` as
            specified by the ISO 8601 standard.
        primaryKey:
          type: string
          description: Subscription primary key.
          minLength: 1
          maxLength: 256
        secondaryKey:
          type: string
          description: Subscription secondary key.
          minLength: 1
          maxLength: 256
        stateComment:
          type: string
          description: Optional subscription comment added by an administrator.
      required:
        - userId
        - productId
        - state
        - primaryKey
        - secondaryKey
      description: Subscription details.
    SubscriptionCreateParameters:
      properties:
        userId:
          type: string
          description: User (user id path) for whom subscription is being created in form
            /users/{uid}
        productId:
          type: string
          description: Product (product id path) for which subscription is being created in
            form /products/{productId}
        name:
          type: string
          description: Subscription name.
          minLength: 0
          maxLength: 100
        primaryKey:
          type: string
          description: Primary subscription key. If not specified during request key will
            be generated automatically.
          minLength: 1
          maxLength: 256
        secondaryKey:
          type: string
          description: Secondary subscription key. If not specified during request key will
            be generated automatically.
          minLength: 1
          maxLength: 256
        state:
          type: string
          description: Initial subscription state. If no value is specified, subscription
            is created with Submitted state. Possible states are * active – the
            subscription is active, * suspended – the subscription is blocked,
            and the subscriber cannot call any APIs of the product, * submitted
            – the subscription request has been made by the developer, but has
            not yet been approved or rejected, * rejected – the subscription
            request has been denied by an administrator, * cancelled – the
            subscription has been cancelled by the developer or administrator, *
            expired – the subscription reached its expiration date and was
            deactivated.
          enum:
            - suspended
            - active
            - expired
            - submitted
            - rejected
            - cancelled
          x-ms-enum:
            name: SubscriptionState
            modelAsString: false
      required:
        - userId
        - productId
      description: Parameters supplied to the Create subscription operation.
    SubscriptionUpdateParameters:
      properties:
        userId:
          type: string
          description: "User identifier path: /users/{uid}"
        productId:
          type: string
          description: "Product identifier path: /products/{productId}"
        expirationDate:
          type: string
          format: date-time
          description: "Subscription expiration date. The setting is for audit purposes
            only and the subscription is not automatically expired. The
            subscription lifecycle can be managed by using the `state` property.
            The date conforms to the following format: `yyyy-MM-ddTHH:mm:ssZ` as
            specified by the ISO 8601 standard."
        name:
          type: string
          description: Subscription name.
        primaryKey:
          type: string
          description: Primary subscription key.
          minLength: 1
          maxLength: 256
        secondaryKey:
          type: string
          description: Secondary subscription key.
          minLength: 1
          maxLength: 256
        state:
          type: string
          description: Subscription state. Possible states are * active – the subscription
            is active, * suspended – the subscription is blocked, and the
            subscriber cannot call any APIs of the product, * submitted – the
            subscription request has been made by the developer, but has not yet
            been approved or rejected, * rejected – the subscription request has
            been denied by an administrator, * cancelled – the subscription has
            been cancelled by the developer or administrator, * expired – the
            subscription reached its expiration date and was deactivated.
          enum:
            - suspended
            - active
            - expired
            - submitted
            - rejected
            - cancelled
          x-ms-enum:
            name: SubscriptionState
            modelAsString: false
        stateComment:
          type: string
          description: Comments describing subscription state change by the administrator.
      description: Parameters supplied to the Update subscription operation.