openapi: 3.0.0
info:
  title: Apigee Consumer Credential Management
  description: This service provides the access to manage client credentials on the Apigee platform. It offers APIs to check expiry of existing credentials, rotate expiring credentials and revoke compromised credentials. All the APIs are OAuth2.0 protected and require valid client credentials to generate bearer token for a secure access.
  version: '1.0'
  termsOfService: https://developer.fil.com/legal
  contact:
    name: The API Security Team
    email: FIL-APISecurity@FILPROD.onmicrosoft.com
servers:
  - url: https://api.fil.com/api-platform/v1
  - url: https://stage.api.fil.com/api-platform/v1
security:
  - OAuth2: []
paths:
  /credentials/expiry:
    post:
      tags:
        - Check Credentials Expiry
      summary: Check expiry of the active client credentials.
      operationId: Credentials Expiry
      parameters:
        - name: requestId
          in: header
          required: false
          schema:
            type: string
            pattern: '[a-zA-Z0-9\-_]+'
          description: Represents a unique request id. Used to track a request flow across different systems.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExpiryRequest'
        required: true
      responses:
        '200':
          description: Request has been successfully processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpiryResponse'
        '400':
          description: Bad request. Refer to the moreinfo section for details. Please check that you have entered the correct information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '401':
          description: Unauthorised access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '404':
          description: Item not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '429':
          description: There are too many requests in a given amount of time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '500':
          description: There was an internal issue calling the service. This is likely to be a permanent error. Please contact FIL for support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
  /credentials/revoke:
    post:
      tags:
        - Revoke Credentials
      summary: Revoke the existing credentials.
      operationId: Revoke Credentials
      parameters:
        - name: requestId
          in: header
          required: false
          schema:
            type: string
            pattern: '[a-zA-Z0-9\-_]+'
          description: Represents a unique request id. Used to track a request flow across different systems.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevokeRequest'
        required: true
      responses:
        '204':
          description: Request has been successfully processed.
        '400':
          description: Bad request. Refer to the moreinfo section for details. Please check that you have entered the correct information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '401':
          description: Unauthorised access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '404':
          description: Item not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '429':
          description: There are too many requests in a given amount of time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '500':
          description: There was an internal issue calling the service. This is likely to be a permanent error. Please contact FIL for support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
  /credentials:
    post:
      tags:
        - Rotate Credentials
      summary: Rotate expiring credentials with new set of client credentials.
      operationId: Create Credentials.
      parameters:
        - name: requestId
          in: header
          required: false
          schema:
            type: string
            pattern: '[a-zA-Z0-9\-_]+'
          description: Represents a unique request id. Used to track a request flow across different systems.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRequest'
        required: true
      responses:
        '200':
          description: Request has been successfully processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateResponse'
        '400':
          description: Bad request. Refer to the moreinfo section for details. Please check that you have entered the correct information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '401':
          description: Unauthorised access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '404':
          description: Item not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '429':
          description: There are too many requests in a given amount of time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '500':
          description: There was an internal issue calling the service. This is likely to be a permanent error. Please contact FIL for support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://sandbox.api.fil.com/identity/v1/tokens?grant_type=client_credentials
          scopes:
            read: Grants read access
  schemas:
    ExpiryResponse:
      type: object
      properties:
        appName:
          description: Apigee App name residing the existing credentials.
          type: string
          example: APP00050-Health-Check
        consumerKey:
          description: Existing Consumer Key aka Client Id aka Client key.
          type: string
          example: Z7n6K8tGdtatog0s4bJCymIdZxwSEu49
        expiry:
          description: Expiry time of the existing credentials.
          type: string
          example: Fri Nov 29 2024 15:09:19 GMT-0000 (UTC)
        status:
          description: Status of the existing credentials
          type: string
          example: approved
    ExpiryRequest:
      required:
        - consumerKey
      description: Payload fields required to expiry of Client Credentials.
      type: object
      properties:
        consumerKey:
          description: Existing Consumer Key aka Client Id aka Client key.
          type: string
          example: Z7n6K8tGdtatog0s4bJCymIdZxwSEu49
    RevokeRequest:
      required:
        - consumerKey
      description: Payload fields required to revoke Client Credentials.
      type: object
      properties:
        consumerKey:
          description: Existing Consumer Key aka Client Id aka Client key.
          type: string
          example: Z7n6K8tGdtatog0s4bJCymIdZxwSEu49
    CreateRequest:
      required:
        - appName
        - consumerKey
        - durationInHours
        - deleteConsumerKey
      description: Payload fields required to generate Client Credentials.
      type: object
      properties:
        appName:
          description: Apigee App name residing the existing credentials.
          type: string
          example: APP00050-Health-Check
        consumerKey:
          description: Existing Consumer Key aka Client Id aka Client key.
          type: string
          example: Z7n6K8tGdtatog0s4bJCymIdZxwSEu49
        durationInHours:
          description: The number of hours for which new generated credentials will be valid. Pass "-1" if require never expiry keys.  Ex. 6 months equals to 4380 hours.
          type: number
          example: 4320
        deleteConsumerKey:
          description: "Yes/No. \n\nYes - if you want to delete the expiring credentials of which the Consumer key is supplied in the request.\n\n No - if you don't want to explicitly delete existing credentials while rotating them instead let them expire on their own.\n\n 
            **NOTE** - It can only delete credentials with no custom conifgurations like Trusted Headers or FIL_ID. Use Revoke operation in case you want to explicitly disable such client credentials."
          type: string
          example: 'No'
    CreateResponse:
      description: Client Credential details returned in response.
      type: object
      properties:
        consumerKey:
          description: Newly generated Consumer Key.
          type: string
          example: 3L3yAgktIQRxiHN4I3z61ql3UxFQKGEw
        consumerSecret:
          description: New generated consumer secret
          type: string
          example: XKxv2tJbHcrscQAM
        expiresAt:
          description: New generated credentials expiry time.
          type: string
          example: Tue Aug 25 2020 12:06:00 GMT-0000 (UTC)
        status:
          description: If the generated credentials are approved or pending for approval.
          type: string
          example: approved
        keyExistsInIdentityKVM:
          description: If the incoming key exists in identity-v1 KVM.
          type: string
          example: 'No'
        deleteMessage:
          description: If deleteConsumerKey is yes, it give information if key is deleted or not. If not deleted we will supply a reason
          type: string
          example: Do Not delete payload key
    Message:
      required:
        - moreInfo
      type: object
      properties:
        moreInfo:
          $ref: '#/components/schemas/MoreInfo'
    MoreInfo:
      required:
        - code
        - userMessage
      type: object
      properties:
        code:
          type: string
          maxLength: 50
          example: PP400
        developerMessage:
          type: array
          items:
            type: string
          description: message details.
          example: Missing fields
        userMessage:
          type: string
          maxLength: 100
          example: Mandatory fields Missing
        moreInfo:
          type: string
        errorMessages:
          type: array
          items:
            $ref: '#/components/schemas/ErrorMessage'
    ErrorMessage:
      type: object
      required:
        - code
        - message
      properties:
        argument:
          $ref: '#/components/schemas/Argument'
        code:
          type: string
          maxLength: 50
        userMessage:
          type: string
          maxLength: 100
    Argument:
      type: object
      required:
        - key
      properties:
        key:
          type: string
          description: Field name for the returned message.
          maxLength: 50
        value:
          type: string
          description: Erroneous value passed in request. Value will be sanitized for any HTML code before being returned.
          maxLength: 200