{
"openapi": "3.0.0",
"info": {
"title": "OIDC API Service",
"version": "1.09.01",
"license": {}
},
"paths": {
"/community/{community}/.well-known/openid-configuration": {
"get": {
"summary": "Discovery",
"description": "Get discovery
\n\n\n| **Returns** |\n|-------------------------------------------|\n\nReturns a set of OpenID Connect values that can be retrieved by OIDC clients\n",
"tags": [
"Discovery"
],
"parameters": [
{
"name": "community",
"in": "path",
"required": true,
"description": "community name",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OIDC discovery end-point",
"headers": {
"x-next": {
"description": "OIDC discovery information",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Discovery"
}
}
}
},
"default": {
"description": "unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorOIDC"
}
}
}
}
}
}
},
"/community/{community}/v1/jwks": {
"get": {
"summary": "JWKS",
"description": "Get jwks
\n\n\n| **Returns** |\n|-------------------------------------------|\n\nUsed to request the key(s) an OpenID client can use to sign and/or encrypt token\n",
"tags": [
"JWKS"
],
"parameters": [
{
"name": "community",
"in": "path",
"required": true,
"description": "community name",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OIDC JWKS endpoint",
"headers": {
"x-next": {
"description": "OIDC JWKS information",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/keys"
}
}
}
},
"default": {
"description": "unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorOIDC"
}
}
}
}
}
}
},
"/community/{community}/v1/introspect": {
"post": {
"security": [
{
"basicAuth": []
}
],
"summary": "Introspection",
"description": "**Note:** Requires basicAuth with client id as username and client secret as password\n\n| **Returns** |\n|-------------------------------------------|\nReturns the active state of an OAuth 2.0 Access token and to determine meta-information about this token\n",
"tags": [
"Introspection"
],
"requestBody": {
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"properties": {
"token": {
"description": "access token",
"type": "string"
}
},
"required": [
"token"
]
}
}
}
},
"parameters": [
{
"name": "community",
"in": "path",
"required": true,
"description": "community name",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OIDC introspection",
"headers": {
"x-next": {
"description": "OIDC introspection",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Introspect"
}
}
}
},
"default": {
"description": "unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorOIDC"
}
}
}
}
}
}
},
"/community/{community}/v1/authorize": {
"get": {
"summary": "Authorize",
"description": "Used to request an authorization code.
\n**Note:**This api does not work on swagger, please use postman based on details on swagger\n\n| **Note: this endpoint redirects** |\n|-----------------------------------------------------------------|\n\nThis end-point requires redirecting to OIDC consent end-point.\n",
"tags": [
"Authorize"
],
"parameters": [
{
"in": "query",
"name": "state",
"type": "string",
"description": "Opaque value used to maintain state between the request and the callback"
},
{
"in": "query",
"name": "nonce",
"type": "string",
"description": "string value used to associate a Client session with an ID Token"
},
{
"in": "query",
"name": "client_id",
"required": true,
"type": "string",
"description": "OAuth 2.0 Client Identifier valid at the Authorization Server"
},
{
"in": "query",
"name": "response_type",
"required": true,
"type": "string",
"description": "OAuth 2.0 Response Type value that determines the authorization processing flow"
},
{
"in": "query",
"name": "scope",
"required": true,
"type": "string",
"description": "specify the access privileges when issuing an Access Token"
},
{
"in": "query",
"name": "redirect_uri",
"required": true,
"type": "string",
"description": "Redirection URI to which the response will be sent"
},
{
"name": "community",
"in": "path",
"required": true,
"description": "community name",
"type": "string"
}
],
"responses": {
"303": {
"description": "Redirect to admin oidc redirect endpoints (oidc, oidc-authenticator) for consent input or redirect to redirect_uri with error if there is an error"
}
}
},
"post": {
"summary": "Authorize",
"description": "Used to request an authorization code.\n- If the **proof_of_authentication_jwt** token is specified and the operation is successful, then the response contains a **location** header
\n containing a URL to the **redirect_uri** containing an authorization code parameter. If the operation fails, the then the response contains a
\n **location** header containing a URL to the **redirect_uri** and an error parameter.
\n- If the **proof_of_authentication_jwt** is **NOT** specified then this API does not work correctly. It will redirect to the AdminX UI oidc consent endpoint page.
\n The AdminX returns the javascript code for the consent page in the response body panel.
\n **Please use Postman for the non-proof_of_authentication_jwt use case.**\n",
"tags": [
"Authorize"
],
"requestBody": {
"description": "Request body parameters",
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"properties": {
"client_id": {
"description": "OAuth 2.0 Client Identifier valid at the Authorization Server",
"type": "string"
},
"response_type": {
"description": "OAuth 2.0 Response Type value that determines the authorization processing flow",
"type": "string"
},
"scope": {
"description": "Specify the access privileges. If **proof_of_authentication_jwt** is specified then the scopes **MUST** be 'openid email profile'.",
"type": "string"
},
"redirect_uri": {
"description": "Redirection URI to which the response will be sent",
"type": "string"
},
"proof_of_authentication_jwt": {
"description": "Token used to prove authentication",
"type": "string"
},
"state": {
"description": "Opaque value used to maintain state between the request and the callback",
"type": "string"
},
"nonce": {
"description": "String value used to associate a Client session with an ID Token",
"type": "string"
}
},
"required": [
"client_id",
"redirect_uri",
"scope",
"response_type"
]
}
}
}
},
"parameters": [
{
"name": "community",
"in": "path",
"required": true,
"description": "community name",
"type": "string"
}
],
"responses": {
"200": {
"description": "- If the **proof_of_authentication_jwt token** is specified then code or error is in the location header.\n"
},
"303": {
"description": "- If the **proof_of_authentication_jwt token** is **NOT** specified then swagger will not display the AdminX consent page.
\n Please use Postman for this use case (using details in swagger).\n"
}
}
}
},
"/community/{community}/v1/token": {
"post": {
"security": [
{
"basicAuth": []
}
],
"summary": "Request Tokens",
"description": "Used to request tokens. \n**Note:** Requires basicAuth with client id as username and client secret as password\n\n\n| **Response** |\n|---------------------------------------------------------------|\nReturns access, id and refresh tokens.\n",
"tags": [
"Request Token"
],
"requestBody": {
"description": "Request body parameters",
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"properties": {
"grant_type": {
"description": "Either 'authorization_code' or 'refresh_token'",
"type": "string"
},
"code": {
"description": "the authorization code returned by the authorize redirect",
"type": "string"
},
"redirect_uri": {
"description": "Redirection URI to which the response will be sent",
"type": "string"
}
},
"required": [
"grant_type",
"redirect_uri",
"code"
]
}
}
}
},
"parameters": [
{
"name": "community",
"in": "path",
"required": true,
"description": "community name",
"type": "string"
}
],
"responses": {
"200": {
"description": "Tokens",
"headers": {
"x-next": {
"description": "OIDC tokens",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccessToken"
}
}
}
},
"default": {
"description": "unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorOIDC"
}
}
}
}
}
}
},
"/community/{community}/v1/interaction/{uid}/eam-context": {
"get": {
"summary": "EAM Context",
"description": "Fetch EAM pre-authentication context (oid/tid) from a server-side interaction record.
\n\nThis endpoint is called by nodex-admin-api during the Entra EAM flow to retrieve\nthe oid and tid extracted from the validated id_token_hint. These values are never\nsent to the browser.
\n\nRequires ECDSA service-to-service authentication (publickey, requestid, licensekey headers).\n",
"tags": [
"EAM"
],
"security": [
{
"keyId": []
},
{
"keySecret": []
},
{
"license": []
}
],
"parameters": [
{
"name": "community",
"in": "path",
"required": true,
"description": "Community name",
"schema": {
"type": "string"
}
},
{
"name": "uid",
"in": "path",
"required": true,
"description": "OIDC interaction UID",
"schema": {
"type": "string"
}
},
{
"name": "requestid",
"in": "header",
"required": true,
"description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) / Try Authorize 🔒",
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
}
],
"responses": {
"200": {
"description": "EAM context retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"oid": {
"type": "string",
"description": "Azure AD object ID from the validated id_token_hint"
},
"tid": {
"type": "string",
"description": "Azure AD tenant ID from the validated id_token_hint"
}
}
}
}
}
},
"401": {
"description": "Unauthorized \u2014 missing or invalid service authentication headers"
},
"404": {
"description": "Interaction not found or not an EAM interaction"
}
}
}
},
"/servicekeys": {
"get": {
"summary": "Get service keys",
"description": "This endpoint returns available service keys.\nThe license you are using must be of authLevel 'system'\n\n| **Headers** |\n|----------------------------------------------|\n\n### licensekey (required)\nLicense key encrypted with ECDSA\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now\n\n### publickey (required)\nPublic key\n\n| **Returns** |\n|----------------------------------------------|\n\nReturns array with service keys\n",
"tags": [
"Service Key"
],
"security": [
{
"keyId": []
},
{
"keySecret": []
},
{
"license": []
}
],
"parameters": [
{
"name": "requestid",
"in": "header",
"description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
},
{
"name": "publickey",
"in": "header",
"description": "Public Key / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
},
{
"name": "licensekey",
"in": "header",
"description": "License key encrypted with ECDSA / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServiceKeysResponse"
}
}
}
},
"400": {
"description": "Invalid request"
},
"401": {
"description": "Unauthorized"
},
"500": {
"description": "Internal Server Error"
}
}
}
},
"/servicekey/{keyId}": {
"delete": {
"summary": "Reset Service Key",
"description": "This endpoint resets service key for given keyId. Deletes current one and recreates a new one.\nThe license you are using must be of authLevel 'system'\n\n| **Parameters** |\n|----------------------------------------------|\n\n### keyId (required)\nThe keyId of service key to reset\n\n| **Headers** |\n|----------------------------------------------|\n\n### licensekey (required)\nLicense key encrypted with ECDSA\n\n### requestid (required)\nJSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now\n\n### publickey (required)\nPublic key\n\n| **Returns** |\n|----------------------------------------------|\n\nReturns re-created service key\n",
"tags": [
"Service Key"
],
"security": [
{
"keyId": []
},
{
"keySecret": []
},
{
"license": []
}
],
"parameters": [
{
"name": "keyId",
"in": "path",
"description": "keyId of service key to reset",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "requestid",
"in": "header",
"description": "JSON string encrypted with ECDSA which should contain \"appid\" (string), \"uuid\" (string) and \"ts\" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
},
{
"name": "publickey",
"in": "header",
"description": "Public Key / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
},
{
"name": "licensekey",
"in": "header",
"description": "License key encrypted with ECDSA / Try Authorize 🔒",
"required": true,
"schema": {
"type": "string",
"example": "Do not enter anything, use 'Authorize' fields"
}
}
],
"responses": {
"204": {
"$ref": "#/components/schemas/NoContent"
}
}
}
},
"/sd": {
"get": {
"summary": "Get all service directories.",
"description": "Get all service directories.\n\n| **Returns** |\n|-------------------------------------------|\n\nReturns all service directories.\n",
"tags": [
"Service Directory"
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetServiceComponentsResponse"
}
}
}
}
}
}
},
"/publickeys": {
"get": {
"summary": "Get system's public key.",
"description": "Get system's public key.\n\n| **Returns** |\n|-------------------------------------------|\n\nReturns a public key object\n",
"tags": [
"Public Key"
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicKeyResponse"
}
}
}
},
"401": {
"description": "Invalid hawk signature / ID found."
}
}
}
},
"/healthz": {
"get": {
"summary": "Get healthz.",
"description": "Get healthz
\n\n\n| **Returns** |\n|-------------------------------------------|\n\nReturns a healthz object\n - ```version = ..```
\n\n - ```git-tag```: When code is compiled from a git-tag, this must carry the tag name. This should match one of the git tags.\n - ```commit-id```: This is the git-commit-id. eg: When code is built from this, the hex code, in the end, is the commit it.\n - ```dob```: Date Of Build. This is epoc-time-in-se\tconds that tell the time when the build was created.\n - \u200bif the code is not built from a git-tag, then the ```version =\ufffc.```\n",
"tags": [
"Healthz"
],
"responses": {
"200": {
"description": "Success\n\n```\n{\n \"status\": \"all services operational\",\n \"publicKey\": \"string\" //same as /publickeys endpoint,\n \"code\": \"200\",\n \"version\": \"\" //as defined above\n}\n```\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HealthzResponse"
}
}
}
}
}
}
},
"/environment": {
"get": {
"description": "Provide details regarding the environments.\n| **Returns** |\n|-------------------------------------------|\n\nReturns an environment object\n",
"tags": [
"Environment"
],
"security": [
{
"license": []
}
],
"responses": {
"200": {
"description": "Success"
}
}
}
},
"/ecdsa_helper/{method}": {
"post": {
"summary": "Encrypt and decrypt the data string by public key and private key.",
"description": "Encrypt and decrypt the data string by public key and private key.\n\n| **Parameters** |\n|----------------------------------------------|\n\n### method (optional)\nThe method parameter is type of enum. Default value is encrypt.
\nThis parameter only accepts following values
\n **encrypt**, **decrypt**\n\n\n| **Request Body** |\n|----------------------------------------------|\n\n\n### dataStr (required)\nThe dataStr key is type of string.\n\n
\n### publicKey (required)\nThe publicKey is type of string.\n\n
\n### privateKey (required)\nThe privateKey is type of string.\n\n| **Returns** |\n|-------------------------------------------|\n\nReturns the encrypted/decrypted string.
\nThis API throw an error if something goes wrong. A common source of error is public or private key is not valid.\n",
"tags": [
"ECDSA Helper"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EcdsaEncryptDecryptRequest"
}
}
}
},
"parameters": [
{
"in": "path",
"name": "method",
"schema": {
"type": "string",
"enum": [
"encrypt",
"decrypt"
],
"default": "encrypt"
}
}
],
"responses": {
"200": {
"description": "successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EcdsaEncryptDecryptResponse"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"PublicKeyResponse": {
"type": "object",
"properties": {
"publicKey": {
"type": "string"
}
},
"example": {
"publicKey": ""
}
},
"ServiceKey": {
"type": "object",
"required": [
"tag",
"keyId",
"keySecret",
"type"
],
"properties": {
"tag": {
"type": "string",
"description": "service ecdsa"
},
"keyId": {
"type": "string",
"description": "ecdsa publicKey"
},
"keySecret": {
"type": "string",
"description": "ecdsa private key"
},
"type": {
"type": "string",
"description": "default = ecdsa | hawk"
}
},
"example": {
"tag": "xxxxx",
"keyId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
"keySecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
"type": "xxxxx"
}
},
"ValidationError": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error content"
},
"param": {
"type": "string",
"description": "Field name"
},
"xml": {
"name": "ValidationError"
}
}
},
"ServiceKeysResponse": {
"type": "array",
"description": "Service keys array",
"items": {
"$ref": "#/components/schemas/ServiceKey"
}
},
"NoContent": {
"description": "This API returns no content"
},
"HealthzResponse": {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"publicKey": {
"type": "string"
},
"code": {
"type": "string"
},
"version": {
"type": "string"
}
},
"example": {
"status": "all services operational",
"publicKey": "//same as /publickeys endpoint",
"code": "200",
"version": "xxxx.xxxx.xxxx"
}
},
"GetServiceComponentsResponse": {
"type": "object",
"properties": {
"name1": {
"type": "string"
},
"name2": {
"type": "string"
},
"name3": {
"type": "string"
}
},
"example": {
"name1": "https://xxx.xxxxxx.xxx/xxxxx",
"name2": "https://xxx.xxxxxx.xxx/xxxxx",
"name3": "https://xxx.xxxxxx.xxx/xxxxx"
}
},
"EcdsaEncryptDecryptRequest": {
"type": "object",
"properties": {
"dataStr": {
"type": "string"
},
"publicKey": {
"type": "string"
},
"privateKey": {
"type": "string"
}
},
"example": {
"dataStr": "Hey, This is example data string.",
"publicKey": "xxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx=",
"privateKey": "xxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx="
}
},
"EcdsaEncryptDecryptResponse": {
"type": "object",
"properties": {
"data": {
"type": "string"
}
},
"example": {
"data": "xxxxxxxxxxxxxxxxxxxx"
}
},
"Discovery": {
"type": "object",
"properties": {
"authorization_endpoint": {
"type": "string"
},
"claims_parameter_supported": {
"type": "string"
},
"claims_supported": {
"type": "string"
},
"code_challenge_methods_supported": {
"type": "string"
},
"end_session_endpoint": {
"type": "string"
},
"grant_types_supported": {
"type": "string"
},
"id_token_signing_alg_values_supported": {
"type": "string"
},
"issuer": {
"type": "string"
},
"jwks_uri": {
"type": "string"
},
"authorization_response_iss_parameter_supported": {
"type": "string"
},
"response_modes_supported": {
"type": "string"
},
"response_types_supported": {
"type": "string"
},
"scopes_supported": {
"type": "string"
},
"subject_types_supported": {
"type": "string"
},
"token_endpoint_auth_methods_supported": {
"type": "string"
},
"token_endpoint_auth_signing_alg_values_supported": {
"type": "string"
},
"token_endpoint": {
"type": "string"
},
"request_object_signing_alg_values_supported": {
"type": "string"
},
"request_parameter_supported": {
"type": "string"
},
"request_uri_parameter_supported": {
"type": "string"
},
"require_request_uri_registration": {
"type": "string"
},
"userinfo_endpoint": {
"type": "string"
},
"introspection_endpoint": {
"type": "string"
},
"introspection_endpoint_auth_methods_supported": {
"type": "string"
},
"introspection_endpoint_auth_signing_alg_values_supported": {
"type": "string"
},
"claim_types_supported": {
"type": "string"
}
}
},
"Introspect": {
"type": "object",
"properties": {
"active": {
"type": "string"
},
"sub": {
"type": "string"
},
"client_id": {
"type": "string"
},
"exp": {
"type": "string"
},
"iat": {
"type": "string"
},
"iss": {
"type": "string"
},
"scope": {
"type": "string"
},
"token_type": {
"type": "string"
}
}
},
"AccessToken": {
"type": "object",
"properties": {
"access_token": {
"type": "string"
},
"id_token": {
"type": "string"
},
"refresh_token": {
"type": "string"
},
"scope": {
"type": "string"
},
"token_type": {
"type": "string"
},
"expires_in": {
"type": "integer",
"format": "int32"
}
}
},
"Error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string"
}
}
},
"ErrorOIDC": {
"type": "object",
"required": [
"error_description",
"error"
],
"properties": {
"error": {
"type": "string"
},
"error_description": {
"type": "string"
}
}
},
"JWKS_REC": {
"type": "object",
"properties": {
"crv": {
"type": "string"
},
"x": {
"type": "string"
},
"y": {
"type": "string"
},
"d": {
"type": "string"
},
"kty": {
"type": "string"
},
"kid": {
"type": "string"
},
"alg": {
"type": "string"
},
"use": {
"type": "string"
}
}
},
"keys": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JWKS_REC"
}
}
},
"securitySchemes": {
"keyId": {
"type": "apiKey",
"name": "keyId",
"in": "header",
"description": "ECDSA Public Key"
},
"keySecret": {
"type": "apiKey",
"name": "keySecret",
"in": "header",
"description": "ECDSA Private Key"
},
"license": {
"type": "apiKey",
"name": "license",
"in": "header",
"description": "License key from License Microservice"
},
"basicAuth": {
"type": "http",
"scheme": "basic"
}
}
},
"tags": [
{
"name": "Service Key"
},
{
"name": "Public Key"
},
{
"name": "Healthz"
},
{
"name": "Environment"
},
{
"name": "ECDSA Helper"
}
],
"servers": [
{
"url": "https://pilot-root.1kosmos.net/oauth2/"
}
]
}