Red Hat 3scale Authorization API

openapi: 3.1.0
info:
  title: Red Hat 3scale Account Management Accounts Authorization API
  description: The 3scale Account Management API provides programmatic access to manage developer accounts, applications, application plans, keys, and API subscriptions within the 3scale platform. It enables automation of developer onboarding, subscription management, and application lifecycle operations. All endpoints require admin API credentials and are accessible on the admin domain at {your-domain}-admin.3scale.net.
  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://{domain}-admin.3scale.net/admin/api
  description: 3scale Account Management API
  variables:
    domain:
      default: your-domain
      description: Your 3scale tenant domain
security:
- provider_key: []
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:
    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
    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'
  securitySchemes:
    provider_key:
      type: apiKey
      in: query
      name: access_token
externalDocs:
  description: Red Hat 3scale Admin Portal Guide
  url: https://access.redhat.com/documentation/en-us/red_hat_3scale_api_management/2.14/html/admin_portal_guide/index