ETSI OpenCAPIF (3GPP CAPIF TS 29.222) APIs

openapi: 3.0.0
info:
  description: "API for access control policy.  \n© 2025, 3GPP Organizational Partners\
    \ (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  \nAll rights reserved.\n"
  title: CAPIF_Access_Control_Policy_API
  version: 1.4.0-alpha.1
externalDocs:
  description: 3GPP TS 29.222 V19.4.0 Common API Framework for 3GPP Northbound APIs
  url: https://www.3gpp.org/ftp/Specs/archive/29_series/29.222/
servers:
- url: "{apiRoot}/access-control-policy/v1"
  variables:
    apiRoot:
      default: https://example.com
      description: apiRoot as defined in clause 7.5 of 3GPP TS 29.222
paths:
  /accessControlPolicyList/{serviceApiId}:
    get:
      description: Retrieves the access control policy list.
      operationId: access_control_policy_list_service_api_id_get
      parameters:
      - description: Identifier of a published service API
        explode: false
        in: path
        name: serviceApiId
        required: true
        schema:
          type: string
        style: simple
      - description: Identifier of the AEF
        explode: true
        in: query
        name: aef-id
        required: true
        schema:
          type: string
        style: form
      - description: Identifier of the API invoker
        explode: true
        in: query
        name: api-invoker-id
        required: false
        schema:
          type: string
        style: form
      - description: To filter irrelevant responses related to unsupported features
        explode: true
        in: query
        name: supported-features
        required: false
        schema:
          $ref: '#/components/schemas/SupportedFeatures'
        style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessControlPolicyList'
          description: OK.
        "307":
          description: Temporary Redirect
          headers:
            Location:
              description: An alternative URI of the resource.
              required: true
              schema:
                type: string
        "308":
          description: Permanent Redirect
          headers:
            Location:
              description: An alternative URI of the resource.
              required: true
              schema:
                type: string
        "400":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Bad request
        "401":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Unauthorized
        "403":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Forbidden
        "404":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Not Found
        "406":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Not Acceptable
        "414":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: URI Too Long
        "429":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Too Many Requests
        "500":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Internal Server Error
        "503":
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Service Unavailable
        default:
          description: Generic Error
      x-openapi-router-controller: capif_acl.controllers.default_controller
components:
  responses:
    "307":
      description: Temporary Redirect
      headers:
        Location:
          description: An alternative URI of the resource.
          required: true
          schema:
            type: string
    "308":
      description: Permanent Redirect
      headers:
        Location:
          description: An alternative URI of the resource.
          required: true
          schema:
            type: string
    "400":
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
      description: Bad request
    "401":
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
      description: Unauthorized
    "403":
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
      description: Forbidden
    "404":
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
      description: Not Found
    "406":
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
      description: Not Acceptable
    "414":
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
      description: URI Too Long
    "429":
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
      description: Too Many Requests
    "500":
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
      description: Internal Server Error
    "503":
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
      description: Service Unavailable
    default:
      description: Generic Error
  schemas:
    AccessControlPolicyList:
      description: Represents the access control policy list for a published service
        API.
      example:
        apiInvokerPolicies:
        - apiInvokerId: apiInvokerId
          allowedTotalInvocations: 0
          netSliceInfo:
          - ensi: ensi
            snssai:
              sd: sd
              sst: 37
            nsiId: nsiId
          - ensi: ensi
            snssai:
              sd: sd
              sst: 37
            nsiId: nsiId
          allowedInvocationTimeRangeList:
          - startTime: 2000-01-23T04:56:07.000+00:00
            stopTime: 2000-01-23T04:56:07.000+00:00
          - startTime: 2000-01-23T04:56:07.000+00:00
            stopTime: 2000-01-23T04:56:07.000+00:00
          allowedInvocationsPerSecond: 6
        - apiInvokerId: apiInvokerId
          allowedTotalInvocations: 0
          netSliceInfo:
          - ensi: ensi
            snssai:
              sd: sd
              sst: 37
            nsiId: nsiId
          - ensi: ensi
            snssai:
              sd: sd
              sst: 37
            nsiId: nsiId
          allowedInvocationTimeRangeList:
          - startTime: 2000-01-23T04:56:07.000+00:00
            stopTime: 2000-01-23T04:56:07.000+00:00
          - startTime: 2000-01-23T04:56:07.000+00:00
            stopTime: 2000-01-23T04:56:07.000+00:00
          allowedInvocationsPerSecond: 6
      properties:
        apiInvokerPolicies:
          description: Policy of each API invoker.
          items:
            $ref: '#/components/schemas/ApiInvokerPolicy'
          minItems: 0
          title: apiInvokerPolicies
          type: array
      title: AccessControlPolicyList
      type: object
    ApiInvokerPolicy:
      description: Represents the policy of an API Invoker.
      example:
        apiInvokerId: apiInvokerId
        allowedTotalInvocations: 0
        netSliceInfo:
        - ensi: ensi
          snssai:
            sd: sd
            sst: 37
          nsiId: nsiId
        - ensi: ensi
          snssai:
            sd: sd
            sst: 37
          nsiId: nsiId
        allowedInvocationTimeRangeList:
        - startTime: 2000-01-23T04:56:07.000+00:00
          stopTime: 2000-01-23T04:56:07.000+00:00
        - startTime: 2000-01-23T04:56:07.000+00:00
          stopTime: 2000-01-23T04:56:07.000+00:00
        allowedInvocationsPerSecond: 6
      properties:
        apiInvokerId:
          description: API invoker ID assigned by the CAPIF core function
          title: apiInvokerId
          type: string
        allowedTotalInvocations:
          description: Total number of invocations allowed on the service API by the
            API invoker.
          title: allowedTotalInvocations
          type: integer
        allowedInvocationsPerSecond:
          description: Invocations per second allowed on the service API by the API
            invoker.
          title: allowedInvocationsPerSecond
          type: integer
        allowedInvocationTimeRangeList:
          description: |
            The time ranges during which the invocations are allowed on the service API by the API invoker.
          items:
            $ref: '#/components/schemas/TimeRangeList'
          minItems: 0
          title: allowedInvocationTimeRangeList
          type: array
        netSliceInfo:
          items:
            $ref: '#/components/schemas/NetSliceId'
          minItems: 1
          title: netSliceInfo
          type: array
      required:
      - apiInvokerId
      title: ApiInvokerPolicy
      type: object
    TimeRangeList:
      description: |
        Represents the time range during which the invocation of a service API is allowed by the API invoker.
      example:
        startTime: 2000-01-23T04:56:07.000+00:00
        stopTime: 2000-01-23T04:56:07.000+00:00
      properties:
        startTime:
          description: string with format "date-time" as defined in OpenAPI.
          format: date-time
          title: DateTime
          type: string
        stopTime:
          description: string with format "date-time" as defined in OpenAPI.
          format: date-time
          title: DateTime
          type: string
      title: TimeRangeList
      type: object
    SupportedFeatures:
      description: |
        A string used to indicate the features supported by an API that is used as defined in clause  6.6 in 3GPP TS 29.500. The string shall contain a bitmask indicating supported features in  hexadecimal representation Each character in the string shall take a value of "0" to "9",  "a" to "f" or "A" to "F" and shall represent the support of 4 features as described in  table 5.2.2-3. The most significant character representing the highest-numbered features shall  appear first in the string, and the character representing features 1 to 4 shall appear last  in the string. The list of features and their numbering (starting with 1) are defined  separately for each API. If the string contains a lower number of characters than there are  defined features for an API, all features that would be represented by characters that are not  present in the string are not supported.
      pattern: "^[A-Fa-f0-9]*$"
      title: supportedFeatures
      type: string
    ProblemDetails:
      description: Represents additional information and details on an error response.
      properties:
        type:
          description: string providing an URI formatted according to IETF RFC 3986.
          title: type
          type: string
        title:
          description: "A short, human-readable summary of the problem type. It should\
            \ not change from occurrence to occurrence of the problem. \n"
          title: title
          type: string
        status:
          description: The HTTP status code for this occurrence of the problem.
          title: status
          type: integer
        detail:
          description: A human-readable explanation specific to this occurrence of
            the problem.
          title: detail
          type: string
        instance:
          description: string providing an URI formatted according to IETF RFC 3986.
          title: type
          type: string
        cause:
          description: |
            A machine-readable application error cause specific to this occurrence of the problem. This IE should be present and provide application-related error information, if available.
          title: cause
          type: string
        invalidParams:
          description: |
            Description of invalid parameters, for a request rejected due to invalid parameters.
          items:
            $ref: '#/components/schemas/InvalidParam'
          minItems: 1
          title: invalidParams
          type: array
        supportedFeatures:
          description: |
            A string used to indicate the features supported by an API that is used as defined in clause  6.6 in 3GPP TS 29.500. The string shall contain a bitmask indicating supported features in  hexadecimal representation Each character in the string shall take a value of "0" to "9",  "a" to "f" or "A" to "F" and shall represent the support of 4 features as described in  table 5.2.2-3. The most significant character representing the highest-numbered features shall  appear first in the string, and the character representing features 1 to 4 shall appear last  in the string. The list of features and their numbering (starting with 1) are defined  separately for each API. If the string contains a lower number of characters than there are  defined features for an API, all features that would be represented by characters that are not  present in the string are not supported.
          pattern: "^[A-Fa-f0-9]*$"
          title: supportedFeatures
          type: string
      title: ProblemDetails
      type: object
    Uri:
      description: string providing an URI formatted according to IETF RFC 3986.
      title: type
      type: string
    InvalidParam:
      description: |
        Represents the description of invalid parameters, for a request rejected due to invalid parameters.
      properties:
        param:
          description: "Attribute's name encoded as a JSON Pointer, or header's name."
          title: param
          type: string
        reason:
          description: "A human-readable reason, e.g. \"must be a positive integer\"\
            ."
          title: reason
          type: string
      required:
      - param
      title: InvalidParam
      type: object
    NetSliceId:
      description: |
        Represents the network slice identification information.
      example:
        ensi: ensi
        snssai:
          sd: sd
          sst: 37
        nsiId: nsiId
      nullable: true
      oneOf:
        - required: [snssai]
        - required: [nsiId]
        - required: [ensi]
      properties:
        snssai:
          $ref: '#/components/schemas/Snssai'
        nsiId:
          description: Contains the Identifier of the selected Network Slice instance
          title: NsiId
          type: string
        ensi:
          description: |
            Represents the External Network Slice Information that is used to identify a network slice, as specified in 3GPP TS 33.501.
          title: Ensi
          type: string
      title: NetSliceId
      type: object
    Ensi:
      description: |
        Represents the External Network Slice Information that is used to identify a network slice, as specified in 3GPP TS 33.501.
      title: Ensi
      type: string
    DateTime:
      description: string with format "date-time" as defined in OpenAPI.
      format: date-time
      title: DateTime
      type: string
    Snssai:
      description: |
        When Snssai needs to be converted to string (e.g. when used in maps as key), the string shall be composed of one to three digits "sst" optionally followed by "-" and 6 hexadecimal digits "sd".
      example:
        sd: sd
        sst: 37
      properties:
        sst:
          description: "Unsigned integer, within the range 0 to 255, representing\
            \ the Slice/Service Type.  It indicates the expected Network Slice behaviour\
            \ in terms of features and services. Values 0 to 127 correspond to the\
            \ standardized SST range. Values 128 to 255 correspond  to the Operator-specific\
            \ range. See clause 28.4.2 of 3GPP TS 23.003. Standardized values are\
            \ defined in clause 5.15.2.2 of 3GPP TS 23.501. \n"
          maximum: 255
          minimum: 0
          title: sst
          type: integer
        sd:
          description: |
            3-octet string, representing the Slice Differentiator, in hexadecimal representation. Each character in the string shall take a value of "0" to "9", "a" to "f" or "A" to "F" and shall represent 4 bits. The most significant character representing the 4 most significant bits of the SD shall appear first in the string, and the character representing the 4 least significant bit of the SD shall appear last in the string. This is an optional parameter that complements the Slice/Service type(s) to allow to  differentiate amongst multiple Network Slices of the same Slice/Service type. This IE shall be absent if no SD value is associated with the SST.
          pattern: "^[A-Fa-f0-9]{6}$"
          title: sd
          type: string
      required:
      - sst
      title: Snssai
      type: object
    NsiId:
      description: Contains the Identifier of the selected Network Slice instance
      title: NsiId
      type: string