A.6 CAPIF_Security_API
29.2223GPPCommon API Framework for 3GPP Northbound APIsRelease 18TS
openapi: 3.0.0
info:
title: CAPIF_Security_API
description: |
API for CAPIF security management.
© 2022, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).
All rights reserved.
version: "1.3.0-alpha.1"
externalDocs:
description: 3GPP TS 29.222 V18.0.0 Common API Framework for 3GPP Northbound APIs
url: https://www.3gpp.org/ftp/Specs/archive/29_series/29.222/
servers:
– url: ‘{apiRoot}/capif-security/v1’
variables:
apiRoot:
default: https://example.com
description: apiRoot as defined in clause 7.5 of 3GPP TS 29.222.
paths:
/trustedInvokers/{apiInvokerId}:
get:
parameters:
– name: apiInvokerId
in: path
description: Identifier of an individual API invoker
required: true
schema:
type: string
– name: authenticationInfo
in: query
description: >
When set to ‘true’, it indicates the CAPIF core function to send the
authentication information of the API invoker. Set to false or omitted otherwise.
schema:
type: boolean
– name: authorizationInfo
in: query
description: >
When set to ‘true’, it indicates the CAPIF core function to send the
authorization information of the API invoker. Set to false or omitted otherwise.
schema:
type: boolean
responses:
‘200’:
description: >
The security related information of the API Invoker based on the request
from the API exposing function.
content:
application/json:
schema:
$ref: ‘#/components/schemas/ServiceSecurity’
‘307’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/307’
‘308’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/308’
‘400’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/400’
‘401’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/401’
‘403’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/403’
‘404’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/404’
‘406’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/406’
‘414’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/414’
‘429’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/429’
‘500’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/500’
‘503’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/503’
default:
$ref: ‘TS29122_CommonData.yaml#/components/responses/default’
put:
parameters:
– name: apiInvokerId
in: path
description: Identifier of an individual API invoker
required: true
schema:
type: string
requestBody:
description: create a security context for an API invoker
required: true
content:
application/json:
schema:
$ref: ‘#/components/schemas/ServiceSecurity’
callbacks:
notificationDestination:
‘{request.body#/notificationDestination}’:
post:
requestBody:
required: true
content:
application/json:
schema:
$ref: ‘#/components/schemas/SecurityNotification’
responses:
‘204’:
description: No Content (successful notification)
‘307’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/307’
‘308’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/308’
‘400’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/400’
‘401’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/401’
‘403’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/403’
‘404’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/404’
‘411’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/411’
‘413’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/413’
‘415’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/415’
‘429’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/429’
‘500’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/500’
‘503’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/503’
default:
$ref: ‘TS29122_CommonData.yaml#/components/responses/default’
responses:
‘201’:
description: Successful created.
content:
application/json:
schema:
$ref: ‘#/components/schemas/ServiceSecurity’
headers:
Location:
description: >
Contains the URI of the newly created resource, according to the structure
{apiRoot}/capif-security/v1/trustedInvokers/{apiInvokerId}
required: true
schema:
type: string
‘400’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/400’
‘401’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/401’
‘403’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/403’
‘411’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/411’
‘413’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/413’
‘414’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/414’
‘415’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/415’
‘429’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/429’
‘500’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/500’
‘503’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/503’
default:
$ref: ‘TS29122_CommonData.yaml#/components/responses/default’
delete:
parameters:
– name: apiInvokerId
in: path
description: Identifier of an individual API invoker
required: true
schema:
type: string
responses:
‘204’:
description: No Content (Successful deletion of the existing subscription)
‘307’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/307’
‘308’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/308’
‘400’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/400’
‘401’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/401’
‘403’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/403’
‘404’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/404’
‘429’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/429’
‘500’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/500’
‘503’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/503’
default:
$ref: ‘TS29122_CommonData.yaml#/components/responses/default’
/trustedInvokers/{apiInvokerId}/update:
post:
parameters:
– name: apiInvokerId
in: path
description: Identifier of an individual API invoker
required: true
schema:
type: string
requestBody:
description: Update the security context (e.g. re-negotiate the security methods).
required: true
content:
application/json:
schema:
$ref: ‘#/components/schemas/ServiceSecurity’
responses:
‘200’:
description: Successful updated.
content:
application/json:
schema:
$ref: ‘#/components/schemas/ServiceSecurity’
‘307’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/307’
‘308’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/308’
‘400’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/400’
‘401’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/401’
‘403’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/403’
‘404’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/404’
‘411’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/411’
‘413’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/413’
‘415’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/415’
‘429’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/429’
‘500’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/500’
‘503’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/503’
default:
$ref: ‘TS29122_CommonData.yaml#/components/responses/default’
/trustedInvokers/{apiInvokerId}/delete:
post:
parameters:
– name: apiInvokerId
in: path
description: Identifier of an individual API invoker
required: true
schema:
type: string
requestBody:
description: Revoke the authorization of the API invoker for APIs.
required: true
content:
application/json:
schema:
$ref: ‘#/components/schemas/SecurityNotification’
responses:
‘204’:
description: Successful revoked.
‘307’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/307’
‘308’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/308’
‘400’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/400’
‘401’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/401’
‘403’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/403’
‘404’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/404’
‘411’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/411’
‘413’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/413’
‘415’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/415’
‘429’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/429’
‘500’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/500’
‘503’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/503’
default:
$ref: ‘TS29122_CommonData.yaml#/components/responses/default’
/securities/{securityId}/token:
post:
parameters:
– name: securityId
in: path
description: Identifier of an individual API invoker
required: true
schema:
type: string
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: ‘#/components/schemas/AccessTokenReq’
responses:
‘200’:
description: Successful Access Token Request
content:
application/json:
schema:
$ref: ‘#/components/schemas/AccessTokenRsp’
‘307’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/307’
‘308’:
$ref: ‘TS29122_CommonData.yaml#/components/responses/308’
‘400’:
description: Error in the Access Token Request
content:
application/json:
schema:
$ref: ‘#/components/schemas/AccessTokenErr’
‘401’:
description: Unauthorized
content:
application/json:
schema:
$ref: ‘#/components/schemas/AccessTokenErr’
‘403’:
$ref: ‘TS29571_CommonData.yaml#/components/responses/403’
‘404’:
$ref: ‘TS29571_CommonData.yaml#/components/responses/404’
‘411’:
$ref: ‘TS29571_CommonData.yaml#/components/responses/411’
‘413’:
$ref: ‘TS29571_CommonData.yaml#/components/responses/413’
‘415’:
$ref: ‘TS29571_CommonData.yaml#/components/responses/415’
‘429’:
$ref: ‘TS29571_CommonData.yaml#/components/responses/429’
‘500’:
$ref: ‘TS29571_CommonData.yaml#/components/responses/500’
‘503’:
$ref: ‘TS29571_CommonData.yaml#/components/responses/503’
default:
$ref: ‘TS29571_CommonData.yaml#/components/responses/default’
components:
schemas:
ServiceSecurity:
type: object
description: >
Represents the details of the security method for each service API interface.
When included by the API invoker, it indicates the preferred method of security.
When included by the CAPIF core function, it indicates the security method to be
used for the service API interface.
properties:
securityInfo:
type: array
items:
$ref: ‘#/components/schemas/SecurityInformation’
minimum: 1
notificationDestination:
$ref: ‘TS29122_CommonData.yaml#/components/schemas/Uri’
requestTestNotification:
type: boolean
description: >
Set to true by API invoker to request the CAPIF core function to send a
test notification as defined in in clause 7.6. Set to false or omitted otherwise.
websockNotifConfig:
$ref: ‘TS29122_CommonData.yaml#/components/schemas/WebsockNotifConfig’
supportedFeatures:
$ref: ‘TS29571_CommonData.yaml#/components/schemas/SupportedFeatures’
required:
– securityInfo
– notificationDestination
SecurityInformation:
type: object
description: Represents the interface details and the security method.
properties:
interfaceDetails:
$ref: ‘TS29222_CAPIF_Publish_Service_API.yaml#/components/schemas/InterfaceDescription’
aefId:
type: string
description: Identifier of the API exposing function
apiId:
type: string
description: API identifier
prefSecurityMethods:
type: array
items:
$ref: ‘TS29222_CAPIF_Publish_Service_API.yaml#/components/schemas/SecurityMethod’
minItems: 1
description: Security methods preferred by the API invoker for the API interface.
selSecurityMethod:
$ref: ‘TS29222_CAPIF_Publish_Service_API.yaml#/components/schemas/SecurityMethod’
authenticationInfo:
type: string
description: Authentication related information
authorizationInfo:
type: string
description: Authorization related information
required:
– prefSecurityMethods
oneOf:
– required: [interfaceDetails]
– required: [aefId]
SecurityNotification:
type: object
description: Represents the revoked authorization notification details.
properties:
apiInvokerId:
type: string
description: String identifying the API invoker assigned by the CAPIF core function.
aefId:
type: string
description: String identifying the AEF.
apiIds:
type: array
items:
type: string
minItems: 1
description: Identifier of the service API
cause:
$ref: ‘#/components/schemas/Cause’
required:
– apiInvokerId
– apiIds
– cause
AccessTokenReq:
format: x-www-form-urlencoded
description: Represents the access token request information.
properties:
grant_type:
type: string
enum:
– client_credentials
client_id:
type: string
client_secret:
type: string
scope:
type: string
required:
– grant_type
– client_id
AccessTokenRsp:
type: object
description: Represents the access token response information.
properties:
access_token:
type: string
description: >
JWS Compact Serialized representation of JWS signed JSON object (AccessTokenClaims)
token_type:
type: string
enum:
– Bearer
expires_in:
$ref: ‘TS29122_CommonData.yaml#/components/schemas/DurationSec’
scope:
type: string
required:
– access_token
– token_type
– expires_in
AccessTokenClaims:
type: object
description: Represents the claims data structure for the access token.
properties:
iss:
type: string
scope:
type: string
exp:
$ref: ‘TS29122_CommonData.yaml#/components/schemas/DurationSec’
required:
– iss
– scope
– exp
AccessTokenErr:
type: object
description: Represents an error in the access token request.
properties:
error:
type: string
enum:
– invalid_request
– invalid_client
– invalid_grant
– unauthorized_client
– unsupported_grant_type
– invalid_scope
error_description:
type: string
error_uri:
type: string
required:
– error
Cause:
anyOf:
– type: string
enum:
– OVERLIMIT_USAGE
– UNEXPECTED_REASON
– type: string
description: >
This string provides forward-compatibility with future
extensions to the enumeration but is not used to encode
content defined in the present version of this API.
description: |
Possible values are:
– OVERLIMIT_USAGE:
The revocation of the authorization of the API invoker is due to the overlimit
usage of the service API
– UNEXPECTED_REASON:
The revocation of the authorization of the API invoker is due to unexpected reason.