Binding

Concrete Specification

Prerequisites

• This protocol uses HTTPS (TLS 1.2 or higher) and communicates via RESTful HTTP request/response.

• Endpoints: HTTP methods (GET, POST, PUT, DELETE) are used against specified URIs.

• Data Format: Request and response bodies use JSON format.

• Authentication and Authorization: OAuth 2.0 and OpenID Connect are used.

  For authentication involving natural persons, OpenID Connect (Authorization Code Flow) is used. For system-level access control, OAuth 2.0 (Client Credentials Flow) is used.

  Policy-based authorization control is also provided.

• Security Requirements: TLS 1.2 or higher is required to ensure encrypted communication.

Field Definitions

For each field used in this binding, the following information is provided:

The definitions of the fields used in this protocol are described below. For detailed field definitions of each API, refer to the separately published API Specification.

Each field includes the following information:

• Field Name: Name used within the protocol

• Type: Data type (e.g., integer, string)

• Requirement:

  • R = Required

  • C = Conditional

  • O = Optional

• Request: Used in request messages

• Response: Used in response messages

• Description: Meaning and usage of the field

Header Field Definitions

Field Name	Type	Required	Request	Response	Description
API-Key	String	R	✔		Specifies the API key issued per client application. ODS-specific field
Authorization	String	C	✔		Specifies the access token. Example: Bearer < token >. Not required for authentication flow-related APIs (except password change).
Content-Type	String	R	✔	✔	Specifies the request format.
User-Agent	String	O	✔		Specifies the client user agent.
Accept-Language	String	O	✔		Specifies the client’s preferred language.
X-TrackingID	String	O	✔	✔	Specifies a unique ID used for request tracing. ODS-specific field
Content-Security-Policy	String	O		✔	Specifies content loading and execution policies and controls allowed script and resource origins.
X-Content-Type-Options	String	O		✔	Prevents MIME-type sniffing by browsers and enforces the declared Content-Type.
Strict-Transport-Security	String	O		✔	Enforces HTTPS connections for a specified period and prevents downgrade to HTTP.
Access-Control-Allow-Origin	String	O		✔	CORS header. Specifies permitted origins for cross-origin access.
Access-Control-Allow-Methods	String	O		✔	CORS header. Specifies allowed HTTP methods for cross-origin requests.
Access-Control-Allow-Headers	String	O		✔	CORS header. Specifies allowed request headers for cross-origin requests.
Access-Control-Allow-Credentials	String	O		✔	CORS header. Specifies whether credentials may be included in cross-origin requests.

Payload Field Definitions

Field Name	Type	Required	Request	Response	Description
type	String	R		✔	Sets the URI that identifies the type of execution result.
title	String	R		✔	Sets a description of the execution result.
status	Integer	R		✔	Sets the HTTP status code.
detail	String	R		✔	Sets information required by the ODS operating entity for investigation (e.g., timestamp of error occurrence).
data	String	C		✔	Business data object for successful execution results. Not required in case of error.

Functional Description

Refer to the API Specification for detailed implementations such as Request, Response, Examples, Error lists, and API-specific field definitions.

Category	Function	Description
Authentication	User Identity Verification	Performs user authentication based on the OIDC authorization flow.
Authentication	Client System Authentication	Authenticates a client using the Client Credentials Flow with a client ID and a client secret.
Token Validation / Renewal	Token Introspection	Validates an access token and retrieves its validity and associated information.
Token Validation / Renewal	Access Token Renewal	Reacquires an access token using a refresh token.
Password Management	Password Change	Changes the password of the user corresponding to the ID included in the request.
API Key Validation	API Key Validation	Validates the API key included in the request body.
Authorization	Authorization Model Registration / Retrieval	Registers or retrieves the authorization model used for authorization. Registration is restricted to authorized users only.
Authorization	Authorization Tuple Registration / Retrieval	Registers or retrieves authorization tuples. Registration is restricted to authorized users only.
Authorization	Authorization Decision	Performs authorization evaluation. The API definition conforms to the AuthZEN evaluation endpoint specification.
User / Client Registration	User Registration	Creates a new user.
User / Client Registration	Client Registration	Registers a client and issues a client secret.
Operator Information Management	Operator Information Registration / Retrieval / Update	Performs operations related to operator information.
Office Information Management	Office Information Registration / Retrieval / Update	Performs operations related to office information associated with an operator.

Authentication

This protocol provides the following two authentication flows.

Authentication Flow	Description
Authorization Code Flow	Used in authentication scenarios involving a user. The client redirects the user to the Identity & Trust（L3）’s authentication screen, and after authentication, obtains an access token using the issued authorization code.
Client Credentials Flow	Used in non-interactive authentication scenarios without a user. The client accesses the Identity & Trust（L3）’s client system authentication endpoint using a client ID and a client secret to obtain an access token.

Authentication Information and Identifiers

Authentication Information

The main authentication information used in this protocol is as follows.

Authentication Information	Applicable Flow	Description
login_user_id	Authorization Code Flow	Identifier entered by the user on the login screen in the Authorization Code Flow involving user authentication.
password	Authorization Code Flow	Secret information corresponding to the login user ID.
client_id	Authorization Code Flow / Client Credentials Flow	Identifier that identifies the client (application) in this protocol.
client_secret	Authorization Code Flow / Client Credentials Flow	Secret used by the client to authenticate itself to the Identity & Trust（L3）.

Identifiers

This protocol attaches the following two types of custom claims to issued access tokens for business identification purposes.

1. operator_id (Operator Identifier)

   Information used to identify the operator to which the user or client belongs. This claim is attached to the access token in the following flows.

   • Authorization Code Flow The operator specified at the time of user issuance is attached.

   • Client Credentials Flow The operator specified at the time of client_id issuance is attached.

2. open_system_id (System Identifier)

   Information used to identify the system to which the client belongs. This claim is attached to the access token only in the following flow.

   • Client Credentials Flow

   It is not attached in the Authorization Code Flow (flow involving a user).

Sequence Diagrams

Authorization Code Flow

Refer to the Protocol Flow section of the Protocol specification.

Client Credentials Flow

Token Validation

Token Renewal

Password Change

API Key Validation

Model Registration

Tuple Registration

Authorization Decision

User and Client Registration

Operator Information Management

Office Information Management