{
  "openapi": "3.1.0",
  "info": {
    "title": "Mekarge A3 Authorization Endpoints",
    "version": "2026.05.1",
    "description": "Endpoints based on OAuth 2.0 RFC 6749,  OAuth 2.0 Token Introspection RFC 7662, OpenID Connect Core 1.0, and OpenID Connect Discovery 1.0 Provider Configuration specifications."
  },
  "servers": [
    {
      "url": "https://a3.mekarge.com/auth/{issuer_path}/",
      "variables": {
        "issuer_path": {
          "default": "xxxxxxxx-0123456789abcdef0123456789abcdef",
          "description": "Issuer Path"
        }
      }
    }
  ],
  "paths": {
    "/authorize": {
      "get": {
        "tags": ["OAuth 2.0 RFC 6749"],
        "summary": "Mekarge A3 Authorization Endpoint.",
        "description": "Mekarge A3 Authorization Endpoint with GET method.",
        "operationId": "authorize",
        "parameters": [
          {
            "name": "response_type",
            "in": "query",
            "required": true,
            "description": "Response Type.",
            "schema": {
              "type": "string",
              "enum": ["code"]
            }
          },
          {
            "name": "client_id",
            "in": "query",
            "required": true,
            "description": "Client Id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "redirect_uri",
            "in": "query",
            "required": false,
            "description": "The callback URI where user-agent will be redirected. Must be an absolute URI as defined by RFC 3986 §4.3. Must not include a fragment component.",
            "schema": {
              "type": "string",
              "format": "uri"
            }
          },
          {
            "name": "resource",
            "in": "query",
            "required": false,
            "description": "The Resource URI of the target Resource. This parameter is **REQUIRED** for Clients defined with _MCP Host_ application type. See RFC 8707 for more details.",
            "schema": {
              "type": "string",
              "format": "uri"
            }
          },
          {
            "name": "scope",
            "in": "query",
            "required": false,
            "description": "Space delimited Scope Tokens. Each Scope should consist of the alphabet defined by RFC 6749 §3.3.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "An opaque value used by the client to maintain state between the request and callback.",
            "schema": {
              "type": "string",
              "maxLength": 64
            }
          },
          {
            "name": "code_challenge",
            "in": "query",
            "required": false,
            "description": "PKCE Code Challenge derived from Code Verifier. This parameter is **REQUIRED** for Clients with PKCE Feature enabled. See RFC 7636 for more details.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "code_challenge_method",
            "in": "query",
            "required": false,
            "description": "PKCE Code Verifier transformation method. This parameter is **REQUIRED** for Clients with PKCE Feature enabled. See RFC 7636 for more details.",
            "schema": {
              "type": "string",
              "enum": ["S256", "plain"]
            }
          },
          {
            "name": "nonce",
            "in": "query",
            "required": false,
            "description": "String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. See OpenID Connect Core 1.0 for more details.",
            "schema": {
              "type": "string",
              "maxLength": 32
            }
          },
          {
            "name": "display",
            "in": "query",
            "required": false,
            "description": "Specifies how the Mekarge A3 Authorization Server displays the user interface pages to the End-User. See OpenID Connect Core 1.0 for more details.",
            "schema": {
              "type": "string",
              "enum": ["page", "popup"]
            }
          },
          {
            "name": "prompt",
            "in": "query",
            "required": false,
            "description": "Space-delimited values that specifies whether the Mekarge A3 Authorization Server prompts the End-User for reauthentication. See OpenID Connect Core 1.0 for more details. When present,\n* Value `login` forces reauthentication even for the Clients with Remember Me Feaure enabled.\n * Value `skip` allows to continue Authorization Process without reauthentication for the Clients with Remember Me Feaure enabled. When Remember Me cookie is expired, this option falls back to reauthentication.\n * Value `none` is similar `skip` however triggers error response if Remember Me cookie is expired or the Feature itself is not applicable or not enabled at all.\n\nSee OpenID Connect Core 1.0 for more details.",
            "schema": {
              "type": "string",
              "enum": ["none", "login", "skip"]
            }
          },
          {
            "name": "ui_locales",
            "in": "query",
            "required": false,
            "description": "Space delimited language tag values defined in RFC 5646. Represents the preferred languages for the user interface. See OpenID Connect Core 1.0 for more details.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "login_hint",
            "in": "query",
            "required": false,
            "description": "Hint about the login identifier the End-User might use to log in. See OpenID Connect Core 1.0 for more details.",
            "schema": {
              "type": "string",
              "enum": ["email", "phone_number", "username"]
            }
          },
          {
            "name": "claims_locales",
            "in": "query",
            "required": false,
            "description": "Space delimited language tag values defined in RFC 5646. Represents the preferred languages for Claims being returned in Id Token. See OpenID Connect Core 1.0 for more details.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "claims",
            "in": "query",
            "required": false,
            "description": "UTF-8 encoded JSON with top level member of `id_token`. Requested claims will be passed as attribute keys where values will be fixed as `null` or `{}`. See OpenID Connect Core 1.0 for more details.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect to the client redirection URI. For response_type=code, the redirect carries authorization code parameters in the query component. For response_type=token, the redirect carries access token parameters in the fragment component.",
            "headers": {
              "Location": {
                "description": "Redirection target URI containing authorization response parameters.",
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "400": {
            "description": "Invalid authorization request."
          }
        }
      }
    },
    "/token": {
      "post": {
        "tags": ["OAuth 2.0 RFC 6749"],
        "summary": "Token endpoint",
        "description": "OAuth 2.0 Token Endpoint. Requests use `application/x-www-form-urlencoded` and HTTP POST.\n\nThe request shape depends on `grant_type`.\n\nSupported Client authentication methods:\n* Basic Authentication defined by RFC 7617 (RFC 2617)\n* Post (Http Body) defined by RFC 6749\n* Client Secret JWT defined by RFC 7523",
        "operationId": "token",
        "parameters": [
          {
            "$ref": "#/components/parameters/Mekarge-Request-Id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/AuthorizationCodeGrantType"
                  },
                  {
                    "$ref": "#/components/schemas/ClientCredentialsGrantType"
                  },
                  {
                    "$ref": "#/components/schemas/RefreshTokenGrantType"
                  }
                ],
                "discriminator": {
                  "propertyName": "grant_type",
                  "mapping": {
                    "authorization_code": "#/components/schemas/AuthorizationCodeGrantType",
                    "client_credentials": "#/components/schemas/ClientCredentialsGrantType",
                    "refresh_token": "#/components/schemas/RefreshTokenGrantType"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful token response.",
            "headers": {
              "Mekarge-Request-Id": {
                "$ref": "#/components/headers/Mekarge-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenSuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid token request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Client authentication failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenErrorResponse"
                }
              }
            }
          }
        },
        "security": []
      }
    },
    "/introspect": {
      "post": {
        "tags": ["OAuth 2.0 Token Introspection RFC 7662"],
        "summary": "Token introspection endpoint",
        "description": "OAuth 2.0 Token Introspection endpoint as defined by RFC 7662.",
        "operationId": "introspect",
        "parameters": [
          {
            "$ref": "#/components/parameters/Mekarge-Request-Id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/IntrospectionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token introspection response.",
            "headers": {
              "Mekarge-Request-Id": {
                "$ref": "#/components/headers/Mekarge-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IntrospectionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed introspection request."
          },
          "401": {
            "description": "Introspection caller authentication failed."
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/.well-known/openid-configuration": {
      "get": {
        "tags": ["OpenID Connect"],
        "summary": "OpenID Provider Configuration",
        "description": "OpenID Connect Discovery provider configuration response.",
        "operationId": "openid_configuration",
        "parameters": [
          {
            "$ref": "#/components/parameters/Mekarge-Request-Id"
          }
        ],
        "responses": {
          "200": {
            "description": "Provider metadata document.",
            "headers": {
              "Mekarge-Request-Id": {
                "$ref": "#/components/headers/Mekarge-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenIDProviderMetadata"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Bearer token authentication."
      }
    },
    "headers": {
      "Mekarge-Request-Id": {
        "description": "Request indentifier. Mekarge A3 server will generate one when it is not given.",
        "required": true,
        "schema": {
          "type": "string"
        }
      }
    },
    "parameters": {
      "Mekarge-Request-Id": {
        "name": "Mekarge-Request-Id",
        "in": "header",
        "description": "Request indentifier. Mekarge A3 server will generate one when it is not given.",
        "required": false,
        "schema": {
          "type": "string",
          "maxLength": 36
        }
      }
    },
    "schemas": {
      "AuthorizationCodeGrantType": {
        "type": "object",
        "required": ["grant_type", "code"],
        "properties": {
          "grant_type": {
            "type": "string",
            "const": "authorization_code"
          },
          "code": {
            "type": "string",
            "description": "The Authorization Code obtained from Mekarge A3 Authorization Server."
          },
          "redirect_uri": {
            "type": "string",
            "format": "uri",
            "description": "Must be equal to the value in Authorization Request if present."
          },
          "resource": {
            "type": "string",
            "format": "uri",
            "description": "The Resource URI of the target Resource. This parameter is **REQUIRED** for Clients defined with _MCP Host_ application type. See RFC 8707 for more details."
          },
          "attestation_profile": {
            "type": "string",
            "description": "The Attestation Profile name. This parameter is **REQUIRED** for Clients defined with _Native_ application type and Attestation Feature is enabled."
          },
          "ear_token": {
            "type": "string",
            "description": "EAR Token containing Appraisals. This parameter is **REQUIRED** for Clients defined with _Native_ application type and Attestation Feature is enabled. See EAT Attestation Results draft document for more details."
          },
          "code_verifier": {
            "type": "string",
            "description": "PKCE Code Verifier. This parameter is **REQUIRED** for Clients with PKCE Feature enabled. See RFC 7636 for more details."
          },
          "client_id": {
            "type": "string",
            "description": "Client Id. This parameter is **REQUIRED** for Clients with `Post (Http Body)` Client Authentication Type."
          },
          "client_secret": {
            "type": "string",
            "description": "Client Secret. This parameter is **REQUIRED** for Clients with `Post (Http Body)` Client Authentication Type."
          },
          "client_assertion_type": {
            "type": "string",
            "const": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
            "description": "This parameter is **REQUIRED** for Clients with `Client Secret JWT` Client Authentication Type. See RFC 7523 for more details."
          },
          "client_assertion": {
            "type": "string",
            "description": "JWT token. This parameter is **REQUIRED** for Clients with `Client Secret JWT` Client Authentication Type. See RFC 7523 for more details."
          }
        },
        "additionalProperties": false
      },
      "ClientCredentialsGrantType": {
        "type": "object",
        "required": ["grant_type"],
        "properties": {
          "grant_type": {
            "type": "string",
            "const": "client_credentials"
          },
          "scope": {
            "type": "string",
            "description": "Space delimited Scope Tokens. Each Scope should consist of the alphabet defined by RFC 6749 §3.3."
          },
          "resource": {
            "type": "string",
            "format": "uri",
            "description": "The Resource URI of the target Resource. This parameter is **REQUIRED** for Clients defined with _MCP Host_ application type. See RFC 8707 for more details."
          },
          "client_id": {
            "type": "string",
            "description": "Client Id. This parameter is **REQUIRED** for Clients with `Post (Http Body)` Client Authentication Type."
          },
          "client_secret": {
            "type": "string",
            "description": "Client Secret. This parameter is **REQUIRED** for Clients with `Post (Http Body)` Client Authentication Type."
          },
          "client_assertion_type": {
            "type": "string",
            "const": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
            "description": "This parameter is **REQUIRED** for Clients with `Client Secret JWT` Client Authentication Type. See RFC 7523 for more details."
          },
          "client_assertion": {
            "type": "string",
            "description": "JWT token. This parameter is **REQUIRED** for Clients with `Client Secret JWT` Client Authentication Type. See RFC 7523 for more details."
          }
        },
        "additionalProperties": false
      },
      "RefreshTokenGrantType": {
        "type": "object",
        "required": ["grant_type", "refresh_token"],
        "properties": {
          "grant_type": {
            "type": "string",
            "const": "refresh_token"
          },
          "refresh_token": {
            "type": "string",
            "description": "The Refresh Token obtained from Mekarge A3 Authorization Server."
          },
          "scope": {
            "type": "string",
            "description": "Space delimited Scope Tokens. Each Scope should consist of the alphabet defined by RFC 6749 §3.3."
          },
          "resource": {
            "type": "string",
            "format": "uri",
            "description": "The Resource URI of the target Resource. This parameter is **REQUIRED** for Clients defined with _MCP Host_ application type. See RFC 8707 for more details."
          },
          "code_verifier": {
            "type": "string",
            "description": "PKCE Code Verifier. See RFC 7636 for more details."
          },
          "client_id": {
            "type": "string",
            "description": "Client Id. This parameter is **REQUIRED** for Clients with `Post (Http Body)` Client Authentication Type."
          },
          "client_secret": {
            "type": "string",
            "description": "Client Secret. This parameter is **REQUIRED** for Clients with `Post (Http Body)` Client Authentication Type."
          },
          "client_assertion_type": {
            "type": "string",
            "const": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
            "description": "This parameter is **REQUIRED** for Clients with `Client Secret JWT` Client Authentication Type. See RFC 7523 for more details."
          },
          "client_assertion": {
            "type": "string",
            "description": "JWT token. This parameter is **REQUIRED** for Clients with `Client Secret JWT` Client Authentication Type. See RFC 7523 for more details."
          }
        },
        "additionalProperties": false
      },
      "TokenSuccessResponse": {
        "type": "object",
        "required": ["access_token", "token_type"],
        "properties": {
          "access_token": {
            "type": "string",
            "description": "Access Token issued by Mekarge A3 Authorization Server."
          },
          "token_type": {
            "type": "string",
            "description": "The type of the token issued by Mekarge A3 Authorization Server.",
            "enum": ["Bearer"]
          },
          "expires_in": {
            "type": "integer",
            "description": "The lifetime in seconds of the Access Token.",
            "minimum": 0
          },
          "id_token": {
            "type": "string",
            "description": "Id Token issued by Mekarge A3 Authorization Server. This token will be issued if it's requested in Scopes and the Client has OpenID Feature enabled."
          },
          "refresh_token": {
            "type": "string",
            "description": "The Refresh Token issued by Mekarge A3 Authorization Server. This token will be issued if it's requested in Scopes and the Client has Refresh Token (Offline Access) Feature enabled."
          },
          "scope": {
            "type": "string",
            "description": "Space delimited Scope Tokens. Each Scope should consist of the alphabet defined by RFC 6749 §3.3."
          }
        },
        "additionalProperties": false
      },
      "TokenErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "invalid_request",
              "invalid_client",
              "invalid_grant",
              "unauthorized_client",
              "unsupported_grant_type",
              "invalid_scope",
              "invalid_target"
            ]
          }
        },
        "additionalProperties": false
      },
      "IntrospectionRequest": {
        "type": "object",
        "required": ["token"],
        "properties": {
          "token": {
            "type": "string",
            "description": "The token string to introspect. Only Access Token introspection is supported."
          },
          "token_type_hint": {
            "type": "string",
            "enum": ["access_token"],
            "description": "Hint about the type of the submitted token."
          }
        },
        "additionalProperties": false
      },
      "IntrospectionResponse": {
        "type": "object",
        "required": ["active"],
        "properties": {
          "active": {
            "type": "boolean",
            "description": "Boolean indicator of whether or not the presented token is currently active."
          },
          "scope": {
            "type": "string",
            "description": "Space delimited Scope Tokens. Each Scope should consist of the alphabet defined by RFC 6749 §3.3."
          },
          "token_type": {
            "type": "string",
            "description": "The type of the token issued by Mekarge A3 Authorization Server."
          },
          "exp": {
            "type": "integer",
            "desciption": "Epoch indicating when this token will expire."
          },
          "iat": {
            "type": "integer",
            "desciption": "Epoch indicating when this token was originally issued."
          },
          "sub": {
            "type": "string",
            "description": "Client Id."
          },
          "jti": {
            "type": "string",
            "description": "String identifier for the token."
          }
        },
        "additionalProperties": false
      },
      "OpenIDProviderMetadata": {
        "type": "object",
        "required": [
          "issuer",
          "authorization_endpoint",
          "response_types_supported",
          "subject_types_supported",
          "id_token_signing_alg_values_supported"
        ],
        "properties": {
          "issuer": {
            "type": "string",
            "format": "uri",
            "description": "Issuer URL of the queried Environment."
          },
          "authorization_endpoint": {
            "type": "string",
            "format": "uri",
            "description": "URL of the Authorization Endpoint of the queried Environment."
          },
          "token_endpoint": {
            "type": "string",
            "format": "uri",
            "description": "URL of the Token Endpoint of the queried Environment."
          },
          "jwks_uri": {
            "type": "string",
            "format": "uri",
            "description": "URL of the JWK Set document of of the queried Environment."
          },
          "scopes_supported": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "JSON array containing a list of the Scopes. Contains `openid`."
          },
          "response_types_supported": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "JSON array containing a list of the response types. Contains `code`, `id_token`, and `id_token token`."
          },
          "grant_types_supported": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "JSON array containing a list of the grant types."
          },
          "acr_values_supported": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "JSON array containing a list of the Authentication Context Class References. Mekarge A3 Authorization Server uses [eIDAS Levels of Assurance](https://ec.europa.eu/digital-building-blocks/sites/spaces/DIGITAL/pages/467110081/eIDAS+Levels+of+Assurance) for classifications."
          },
          "subject_types_supported": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "JSON array containing a list of the Subject Identifier types."
          },
          "id_token_signing_alg_values_supported": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "JSON array containing a list of the JWS signing algorithms."
          },
          "token_endpoint_auth_methods_supported": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "JSON array containing a list of supported Client Authentication methods."
          },
          "token_endpoint_auth_signing_alg_values_supported": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "JSON array containing a list of the supported JWS signing algorithms for the signature on the JWT."
          },
          "display_values_supported": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "JSON array containing a list of the supported display parameter values."
          },
          "claim_types_supported": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "JSON array containing a list of the supported Claim Types"
          }
        },
        "additionalProperties": false
      }
    }
  }
}