Red Hat 3scale Authorization API

openapi: 3.2.0
info:
  title: Red Hat 3scale Service Management Authorization API
  description: The 3scale Service Management API allows API providers to control and manage access to their APIs, track usage, and enforce traffic policies. It is used by the APIcast API gateway to authorize and report API calls in real time. The API supports both API key and OAuth 2.0 based authorization flows.
  version: '1'
  contact:
    name: Red Hat 3scale Support
    url: https://access.redhat.com/support
  termsOfService: https://www.redhat.com/en/about/agreements
servers:
- url: https://su1.3scale.net
  description: 3scale Service Management API
security:
- providerKey: []
tags:
- name: Authorization
  description: Authorize API calls and check access permissions
paths:
  /transactions/authorize.xml:
    get:
      operationId: authorizeTransaction
      summary: Authorize API Transaction
      description: Authorizes an API call by checking whether the application identified by the user key is within its usage limits. Returns success or failure along with current usage data. Used by APIcast before forwarding requests to the backend API.
      tags:
      - Authorization
      parameters:
      - name: provider_key
        in: query
        required: true
        description: The provider key identifying your 3scale account
        schema:
          type: string
      - name: user_key
        in: query
        required: true
        description: The API key of the application making the call
        schema:
          type: string
      - name: service_id
        in: query
        required: false
        description: The ID of the service being accessed
        schema:
          type: string
      - name: usage[hits]
        in: query
        required: false
        description: Number of hits to report with this authorization
        schema:
          type: integer
      responses:
        '200':
          description: Authorization response (success or failure)
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/AuthorizeResponse'
        '403':
          description: Authorization denied
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/AuthorizeErrorResponse'
        '404':
          description: Application not found
  /transactions/authrep.xml:
    get:
      operationId: authorizeAndReport
      summary: Authorize and Report API Transaction
      description: Combines authorization and reporting in a single call. Authorizes the API call and simultaneously reports usage metrics to 3scale. This is the recommended approach for reporting hits and other metrics.
      tags:
      - Authorization
      parameters:
      - name: provider_key
        in: query
        required: true
        description: The provider key identifying your 3scale account
        schema:
          type: string
      - name: user_key
        in: query
        required: true
        description: The API key of the application making the call
        schema:
          type: string
      - name: service_id
        in: query
        required: false
        description: The ID of the service being accessed
        schema:
          type: string
      - name: usage[hits]
        in: query
        required: false
        description: Number of hits to report
        schema:
          type: integer
          default: 1
      responses:
        '200':
          description: Authorization and report successful
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/AuthorizeResponse'
        '403':
          description: Authorization denied or limits exceeded
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/AuthorizeErrorResponse'
components:
  schemas:
    AuthorizeErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - failure
        code:
          type: string
          description: Error code (e.g. user.exceeded_limits)
        message:
          type: string
          description: Human-readable error message
    AuthorizeResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
          - failure
        plan:
          type: string
          description: Name of the application plan
        usage_reports:
          type: array
          items:
            $ref: '#/components/schemas/UsageReport'
    UsageReport:
      type: object
      properties:
        metric:
          type: string
          description: The metric name (e.g. hits)
        period:
          type: string
          description: The time period (minute, hour, day, month, year, eternity)
        period_start:
          type: string
          format: date-time
        period_end:
          type: string
          format: date-time
        max_value:
          type: integer
          description: Maximum allowed value for this period
        current_value:
          type: integer
          description: Current usage value for this period
  securitySchemes:
    providerKey:
      type: apiKey
      in: query
      name: provider_key
externalDocs:
  description: Red Hat 3scale API Authentication Documentation
  url: https://access.redhat.com/documentation/en-us/red_hat_3scale_api_management/2.14/html/api_authentication/index