Trusted API invokers

/trustedInvokers

(NOTE)

n/a

Individual trusted API invoker

/trustedInvokers/{apiInvokerId}

(NOTE)

GET

Retrieve authentication information of an API invoker

PUT

Create a security context for individual API invoker

DELETE

Revoke the authorization of the API invoker

/trustedInvokers/{apiInvokerId}/update

(NOTE)

update (POST)

Update the security context (e.g. re-negotiate the security methods).

/trustedInvokers/{apiInvokerId}/delete

(NOTE)

delete (POST)

Revoke the authorization of the API invoker for some APIs

/securities/{securityId}/token

(NOTE)

token (POST)

Obtain the OAuth 2.0 authorization information

NOTE: The path segment "trustedInvokers" does not follow the related naming convention defined in subclause 7.5.1. The path segment is however kept as currently defined in this specification for backward compatibility considerations.

apiRoot

string

See clause 7.5

apiRoot

string

See clause 7.5

apiInvokerId

string

Identifies an individual API invoker

authenticationInfo

boolean

O

0..1

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.

(NOTE)

authorizationInfo

boolean

O

0..1

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.

(NOTE)

NOTE: The query parameters "authenticationInfo" and "authorizationInfo" do not follow the related naming convention defined in subclause 7.5.1. These query parameters are however kept as currently defined in this specification for backward compatibility considerations.

n/a

ServiceSecurity

M

1

200 OK

The security related information of the API Invoker based on the request from the API exposing function.

n/a

307 Temporary Redirect

Temporary redirection, during resource retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative CAPIF core function.

Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [14].

n/a

308 Permanent Redirect

Permanent redirection, during resource retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative CAPIF core function.

Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [14].

NOTE: The mandatory HTTP error status codes for the GET method listed in table 5.2.6-1 of 3GPP TS 29.122 [14] also apply.

Location

string

M

1

An alternative URI of the resource located in an alternative CAPIF core function.

Location

string

M

1

An alternative URI of the resource located in an alternative CAPIF core function.

n/a

n/a

n/a

204 No Content

Authorization of the API invoker revoked, and a notification is sent to the API invoker as specified in clause 8.5.3.2

n/a

307 Temporary Redirect

Temporary redirection, during resource termination. The response shall include a Location header field containing an alternative URI of the resource located in an alternative CAPIF core function.

Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [14].

n/a

308 Permanent Redirect

Permanent redirection, during resource termination. The response shall include a Location header field containing an alternative URI of the resource located in an alternative CAPIF core function.

Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [14].

NOTE: The mandatory HTTP error status codes for the DELETE method listed in table 5.2.6-1 of 3GPP TS 29.122 [14] also apply.

Location

string

M

1

An alternative URI of the resource located in an alternative CAPIF core function.

Location

string

M

1

An alternative URI of the resource located in an alternative CAPIF core function.

n/a

ServiceSecurity

M

1

Security method request from the API invoker to the CAPIF core function. The request indicates a list of service APIs and a preferred method of security for the service APIs.

The request also includes a notification destination URI for security related notifications.

ServiceSecurity

M

1

201 Created

Security method from the CAPIF core function to the API invoker is based on the received request. The response indicates the security method to be used for the service APIs

The URI of the created resource shall be returned in the "Location" HTTP header.

NOTE: The mandatory HTTP error status codes for the PUT method listed in table 5.2.6-1 of 3GPP TS 29.122 [14] also apply.

Location

string

M

1

Contains the URI of the newly created resource, according to the structure: {apiRoot}/capif-security/v1/trustedInvokers/{apiInvokerId}

update

/trustedInvokers/{apiInvokerId}/update

POST

Update the security instance (e.g. re-negotiate the security methods).

delete

/trustedInvokers/{apiInvokerId}/delete

POST

Revoke the authorization of the API invoker for some APIs

token

/securities/{securityId}/token

POST

Obtain the OAuth 2.0 authorization information

n/a

ServiceSecurity

M

1

Security method request from the API invoker to the CAPIF core function. The request indicates a list of service APIs and a preferred method of security for the service APIs.

The request also includes a notification destination URI for security related notifications.

ServiceSecurity

M

1

200 OK

Security method from the CAPIF core function to the API invoker is based on the received request. The response indicates the security method to be used for the service APIs

n/a

307 Temporary Redirect

Temporary redirection, during security instance modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative CAPIF core function.

Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [14].

n/a

308 Permanent Redirect

Permanent redirection, during security instance modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative CAPIF core function.

Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [14].

NOTE: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 of 3GPP TS 29.122 [14] also apply.

Location

string

M

1

An alternative URI of the resource located in an alternative CAPIF core function.

Location

string

M

1

An alternative URI of the resource located in an alternative CAPIF core function.

n/a

SecurityNotification

M

1

It includes a list of API identifiers for which authorization needs to be revoked for an API invoker.

n/a

204 No Content

Successful case.

The CAPIF core function revoked the authorization of the API invoker for the requested APIs.

n/a

307 Temporary Redirect

Temporary redirection, during authorization revocation. The response shall include a Location header field containing an alternative URI of the resource located in an alternative CAPIF core function.

Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [14].

n/a

308 Permanent Redirect

Permanent redirection, during authorization revocation. The response shall include a Location header field containing an alternative URI of the resource located in an alternative CAPIF core function.

Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [14].

NOTE: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 of 3GPP TS 29.122 [14] also apply.

Location

string

M

1

An alternative URI of the resource located in an alternative CAPIF core function.

Location

string

M

1

An alternative URI of the resource located in an alternative CAPIF core function.

n/a

AccessTokenReq

M

1

This IE shall contain the request information for the access token request.

AccessTokenRsp

M

1

200 OK

This IE shall contain the access token response information.

n/a

307 Temporary Redirect

Temporary redirection, during obtaining authorization information. The response shall include a Location header field containing an alternative URI of the resource located in an alternative CAPIF core function.

Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [14].

n/a

308 Permanent Redirect

Permanent redirection, during obtaining authorization information. The response shall include a Location header field containing an alternative URI of the resource located in an alternative CAPIF core function.

Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [14].

AccessTokenErr

M

1

400 Bad Request

See IETF RFC 6749 [23] clause 5.2.

The specific error shall be indicated in the "error" attribute of the AccessTokenErr data type, containing any of the values:

– invalid_request

– invalid_client

– invalid_grant

– unauthorized_client

– unsupported_grant_type

– invalid_scope

AccessTokenErr

M

1

401 Unauthorized

See IETF RFC 6749 [23] clause 5.2.

The specific error shall be indicated in the "error" attribute of the AccessTokenErr data type, containing value:

– invalid_client

NOTE: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 of 3GPP TS 29.122 [14] also apply.

Location

string

M

1

An alternative URI of the resource located in an alternative CAPIF core function.

Location

string

M

1

An alternative URI of the resource located in an alternative CAPIF core function.

Authorization revoked notification

{notificationDestination}

POST

Notify API invoker that the authorization rights are revoked by the API exposing function.

n/a

SecurityNotification

M

1

Notification with information related to revoked authorization.

n/a

204 No Content

The receipt of the Notification is acknowledged.

n/a

307 Temporary Redirect

Temporary redirection, during notification. The response shall include a Location header field containing an alternative URI representing the end point of an alternative notification destination where the notification should be sent.

Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].

n/a

308 Permanent Redirect

Permanent redirection, during notification. The response shall include a Location header field containing an alternative URI representing the end point of an alternative notification destination where the notification should be sent.

Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].

NOTE: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 of 3GPP TS 29.122 [14] also apply.

Location

string

M

1

An alternative URI representing the end point of an alternative notification destination towards which the notification should be redirected.

Location

string

M

1

An alternative URI representing the end point of an alternative notification destination towards which the notification should be redirected.

AccessTokenClaims

Clause 8.5.4.2.8

Represents the claims data structure for the access token.

AccessTokenErr

Clause 8.5.4.2.9

Represents an error in the access token request.

AccessTokenReq

Clause 8.5.4.2.6

Represents the access token request information.

AccessTokenRsp

Clause 8.5.4.2.7

Represents the access token response information.

Cause

Clause 8.5.4.3.3

Indicates the cause for revoking the API invoker’s authorization to the service API.

SecurityInformation

Clause 8.5.4.2.3

Represents the interface details and the security method.

SecurityNotification

Clause 8.5.4.2.5

Represents the revoked authorization notification details.

ServiceSecurity

Clause 8.5.4.2.2

Represents the details of the security method for each service API interface. When included by the API invoker, it shall indicate the preferred method of security. When included by the CAPIF core function, it shall indicate the security method to be used for the service API interface.

DurationSec

3GPP TS 29.122 [14]

Indicates the duration in seconds.

SecurityMethod

Clause 8.2.4.3.6

Indicates the security method (e.g. PKI).

SupportedFeatures

3GPP TS 29.571 [19]

Used to negotiate the applicability of optional features defined in table 8.5.6-1.

securityInfo

array(SecurityInformation)

M

1..N

Security information for each API interface.

notificationDestination

Uri

M

1

URI where the notification should be delivered to.

requestTestNotification

boolean

O

0..1

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.

Notification_test_event

websockNotifConfig

WebsockNotifConfig

O

0..1

Configuration parameters to set up notification delivery over Websocket protocol as defined in clause 7.6.

Notification_websocket

supportedFeatures

SupportedFeatures

O

0..1

Used to negotiate the supported optional features of the API as described in clause 7.8.

This attribute shall be provided in the HTTP POST request and in the response of successful resource creation.

interfaceDetails

InterfaceDescription

O

0..1

Details of the interface (NOTE)

aefId

string

O

0..1

AEF identifier (NOTE)

apiId

string

C

0..1

API identifier.

If API invoker supplies this IE in the PUT request, CCF shall respond back with this IE and its associated security information.

SecurityInfoPerAPI

prefSecurityMethods

array(SecurityMethod)

M

1..N

Security methods preferred by the API invoker for the API interface

selSecurityMethod

SecurityMethod

O

0..1

Supplied by the CAPIF core function, it indicates the selected security method for the API interface. If it is not provided, it means no common supported security method by the API invoker and the AEF, or the selected security method is not allowed by the local policy in the CAPIF core function.

authenticationInfo

string

O

0..1

Authentication related information

authorizationInfo

string

O

0..1

Authorization related information

NOTE:      Only one of the attributes "aefId" or "interfaceDetails" shall be included.

apiInvokerId

string

M

1

String identifying the API invoker assigned by the CAPIF core function

aefId

string

O

0..1

String identifying the AEF.

apiIds

array(string)

M

1..N

Identifier of the service API

cause

Cause

M

1

The cause for revoking the API invoker authorization to the service API

grant_type

string

M

1

This IE shall contain the grant type as "client_credentials"

(NOTE 3, NOTE 4)

client_id

string

M

1

This IE shall contain the API invoker Identifier.

(NOTE 3)

client_secret

string

O

0..1

This IE when present shall contain the onboarding secret which is got during API invoker onboarding.

(NOTE 3)

scope

string

O

0..1

This IE when present shall contain a list of AEF identifiers and its associated API names for which the access_token is authorized for use.

It takes the format of 3gpp#aefId1:apiName1,apiName2,…apiNameX;aefId2:apiName1,apiName2,…apiNameY;…aefIdN:apiName1,apiName2,…apiNameZ

Using delimeter "#" after the discriminator "3gpp", ":" after AEF identifier, "," between API names and ";" between the last API name of the previous AEF identifier and the next AEF identifier. (NOTE 2)

Example: ‘3gpp#aef-jiangsu-nanjing:3gpp-monitoring-event,3gpp-as-session-with-qos;aef-zhejiang-hangzhou:3gpp-cp-parameter-provisioning,3gpp-pfd-management’

NOTE 1: This data structure shall not be treated as a JSON object. It shall be treated as a key, value pair data structure to be encoded using x-www-urlencoded format as specified in clause 17.13.4.1 of W3C HTML 4.01 Specification [22].

NOTE 2: The scope may contain more space-delimited strings which further add additional access ranges to the scope, the definition of those additional strings is out of the scope of the present document.

NOTE 3: The "grant_type", "client_id" and "client_secret" attributes do not follow the related naming convention defined in subclause 7.2.1. These attributes are however kept as currently defined in this specification for backward compatibility considerations.

NOTE 4: The enumeration value "client_credentials" of the "grant_type" attribute does not follow the related naming convention defined in subclause 7.2.1. This enumeration is however kept as currently defined in this specification for backward compatibility considerations.

access_token

string

M

1

This IE shall contain JWS Compact Serialized representation of the JWS signed JSON object containing AccessTokenClaims (see clause 8.5.4.2.c).

(NOTE 2)

token_type

string

M

1

This IE shall contain the token type (i.e. "Bearer").

(NOTE 2, NOTE 3)

expires_in

DurationSec

M

1

This IE when present shall contain the number of seconds after which the access_token is considered to be expired.

(NOTE 2)

scope

string

O

0..1

This IE when present shall contain a list of AEF identifiers and its associated API names for which the access_token is authorized for use.

It takes the format of 3gpp#aefId1:apiName1,apiName2,…apiNameX;aefId2:apiName1,apiName2,…apiNameY;…aefIdN:apiName1,apiName2,…apiNameZ

Using delimeter "#" after the discriminator "3gpp", ":" after AEF identifier, "," between API names and ";" between the last API name of the previous AEF identifier and the next AEF identifier. (NOTE 1)

Example: ‘3gpp#aef-jiangsu-nanjing:3gpp-monitoring-event,3gpp-as-session-with-qos;aef-zhejiang-hangzhou:3gpp-cp-parameter-provisioning,3gpp-pfd-management’

NOTE 1: The scope may contain more space-delimited strings which further add additional access ranges to the scope, the definition of those additional strings is out of the scope of the present document.

NOTE 2: The "access_token", "token_type" and "expires_in" attributes do not follow the related naming convention defined in clause 7.2.1. These attributes are however kept as currently defined in this specification for backward compatibility considerations.

NOTE 3: The enumeration value "Bearer" of the "token_type" attribute does not follow the related naming convention defined in clause 7.2.1. This enumeration is however kept as currently defined in this specification for backward compatibility considerations.

iss

string

M

1

This IE shall contain the API invoker Identifier.

scope

string

M

1

This IE shall contain a list of AEF identifiers and its associated API names for which the access_token is authorized for use.

It takes the format of 3gpp#aefId1:apiName1,apiName2,…apiNameX;aefId2:apiName1,apiName2,…apiNameY;…aefIdN:apiName1,apiName2,…apiNameZ

Using delimeter "#" after the discriminator "3gpp", ":" after AEF identifier, "," between API names and ";" between the last API name of the previous AEF identifier and the next AEF identifier. (NOTE)

Example: ‘3gpp#aef-jiangsu-nanjing:3gpp-monitoring-event,3gpp-as-session-with-qos;aef-zhejiang-hangzhou:3gpp-cp-parameter-provisioning,3gpp-pfd-management’

exp

DurationSec

M

1

This IE shall contain the number of seconds after which the access_token is considered to be expired.

NOTE: The scope may contain more space-delimited strings which further add additional access ranges to the scope, the definition of those additional strings is out of the scope of the present document.

error

string

M

1

This IE shall contain the error described in IETF RFC 6749 [23], clause 5.2.

Enum:

"invalid_request"

"invalid_client"

"invalid_grant"

"unauthorized_client"

"unsupported_grant_type"

"invalid_scope"

(NOTE 1)

error_description

string

O

0..1

When present, this IE shall contain the human-readable additional information to indicate the error that occurred, as described in IETF RFC 6749 [23], clause 5.2.

(NOTE 2)

error_uri

string

O

0..1

When present, this IE shall contain the URI identifying a human-readable additional information about the error, as described in IETF RFC 6749 [23], clause 5.2.

(NOTE 2)

NOTE 1: The enumeration values "invalid_request", "invalid_client", "invalid_grant", "unauthorized_client", "unsupported_grant_type" and "invalid_scope" of the "error" attribute do not follow the related naming convention defined in clause 7.2.1. These enumeration values are however kept as currently defined in this specification for alignment with definitions in IETF RFC 6749 [23] and backward compatibility considerations.

NOTE 2: The "error_description" and "error_uri" attributes do not follow the related naming convention defined in clause 7.2.1. These attributes are however kept as currently defined in this specification for alignment with definitions in IETF RFC 6749 [23] and backward compatibility considerations.

n/a

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.

invalid_request

400 Bad Request

See IETF RFC 6749 [23]

invalid_client

400 Bad Request,

401 Unauthorized

See IETF RFC 6749 [23]

invalid_grant

400 Bad Request

See IETF RFC 6749 [23]

unauthorized_client

400 Bad Request

See IETF RFC 6749 [23]

unsupported_grant_type

400 Bad Request

See IETF RFC 6749 [23]

invalid_scope

400 Bad Request

See IETF RFC 6749 [23]

NOTE: These enumeration values defined in this table do not follow the related naming convention defined in clause 7.2.1. These enumeration values are however kept as currently defined in this specification for alignment with definitions in IETF RFC 6749 [23].

1

Notification_test_event

Testing of notification connection is supported according to clause 7.6.

2

Notification_websocket

The delivery of notifications over Websocket is supported according to clause 7.6. This feature requires that the Notification_test_event feature is also supported.

3

SecurityInfoPerAPI

Indicates the support of negotiating and obtaining service API security method information per API.