PaymentsNZ · smozely · Jan 6, 2026
diff --git a/dist/v2.3.4/README.md b/dist/v2.3.4/README.md
@@ -0,0 +1,11 @@
+# V2.3.4 schemas
+
+This folder contains schemas for the V2.3.4 security profile. This includes:
+
+- Client authentication [schema](./client-authentication/jwt-bearer-auth-schema.json) (for use with `private_key_jwt` and `client_secret_jwt` authentication)
+- Hybrid flow authorization request [schema](./hybrid-flow/authorization-request-schema.json)
+- CIBA decoupled flow relevant [schemas](./ciba-flow/README.md)
+- ID token [schema](./id-token/id-token-body-schema.json)
+- Generic JWS header [schema](./common/JOSE-header-schema.json)
+
+These are assistive in nature, and supplementary to the Security Profile documentation. It is highly recommended to follow that documentation first.
diff --git a/dist/v2.3.4/ciba-flow/CIBA-authorization-request-object-schema.json b/dist/v2.3.4/ciba-flow/CIBA-authorization-request-object-schema.json
@@ -0,0 +1,109 @@
+{
+  "definitions": {},
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "http://apicentre.paymentsnz.co.nz/schemas/CIBA-authorization-request-object-schema.json",
+  "type": "object",
+  "title": "The schema for the CIBA request object (OIDC/FAPI compliant)",
+  "additionalProperties": false,
+  "required": ["aud", "iss", "exp", "iat", "nbf", "jti", "scope", "ConsentId"],
+  "properties": {
+    "aud": {
+      "$id": "#/properties/aud",
+      "title": "The audiences for the token",
+      "description": "The value should be or include the client ID of the third party",
+      "oneOf": [
+        {
+          "type": "string",
+          "examples": ["https://api.alphanbank.com"],
+          "format": "uri"
+        },
+        {
+          "type": "array",
+          "$id": "#/properties/aud/items",
+          "items": {
+            "type": "string",
+            "pattern": "^(.+)$"
+          },
+          "examples": ["https://api.alphanbank.com"]
+        }
+      ]
+    },
+    "iss": {
+      "$id": "#/properties/iss",
+      "type": "string",
+      "title": "The Issuer of the token",
+      "description": "The value should be the client ID of the third party, unless signed by a different party",
+      "default": "",
+      "examples": ["s6BhdRkqt3"],
+      "pattern": "^(.+)$"
+    },
+    "exp": {
+      "$id": "/properties/exp",
+      "type": "integer",
+      "description": "Expiration time on or after which the ID Token MUST NOT be accepted for processing.",
+      "examples": [1496397168]
+    },
+    "iat": {
+      "$id": "/properties/iat",
+      "type": "integer",
+      "description": "Time at which the JWT was issued.",
+      "examples": [1496361168]
+    },
+    "nbf": {
+      "$id": "/properties/nbf",
+      "type": "integer",
+      "description": "The time before which the ID Token MUST NOT be accepted for processing.",
+      "examples": [1496397168]
+    },
+    "jti": {
+      "$id": "/properties/jti",
+      "type": "string",
+      "description": "The unique identifier of the current JWT token",
+      "examples": ["b8fd0a32-5e00-4b73-b3d8-b4af743b26e8"],
+      "pattern": "^(.+)$"
+    },
+    "scope": {
+      "$id": "#/properties/scope",
+      "type": "string",
+      "title": "The OAuth scopes requested",
+      "description": "Must include 'openid' and any other scopes required",
+      "default": "openid",
+      "examples": ["openid payments"],
+      "pattern": "^openid([ ].*)*$"
+    },
+    "ConsentId": {
+      "$id": "/properties/ConsentId",
+      "type": "string",
+      "pattern": "^(.+)$",
+      "description": "The ID of the consent to which this token is related",
+      "examples": ["20353a34-8be1-4c76-a0ae-4b8c1bbf9ec6"]
+    },
+    "client_notification_token": {
+      "$id": "#/properties/client_notification_token",
+      "type": "string",
+      "title": "The bearer token for third party ping callback",
+      "description": "The API provider must use this to authenticate to the third party for a ping notification",
+      "maxLength": 1024,
+      "pattern": "^[A-Za-z0-9\\-\\._~\\+\\/]+=*$",
+      "examples": [
+        "dGhpc2lzYXRlc3RzdHJpbmd1c2Vkb3RnZW5lcmF0ZWFiYXNlNjR0cmluZw=="
+      ]
+    },
+    "login_hint_token": {
+      "$id": "/properties/login_hint_token",
+      "type": "string",
+      "description": "A JWT token containing information to be used as a hint to the user identity"
+    },
+    "id_token_hint": {
+      "$id": "/properties/id_token_hint",
+      "type": "string",
+      "description": "An ID token that was previously issued to the third party being replayed as a hint to the user identity"
+    },
+    "requested_expiry": {
+      "$id": "/properties/requested_expiry",
+      "type": "integer",
+      "description": "A positive integer allowing the third party to request the expires_in value for auth_req_id the API provider will return",
+      "examples": [300]
+    }
+  }
+}
diff --git a/dist/v2.3.4/ciba-flow/CIBA-authorization-request-response-schema.json b/dist/v2.3.4/ciba-flow/CIBA-authorization-request-response-schema.json
@@ -0,0 +1,32 @@
+{
+  "definitions": {},
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "http://apicentre.paymentsnz.co.nz/schemas/CIBA-authorization-request-response-schema.json",
+  "type": "object",
+  "title": "The schema for the CIBA request response object (OIDC/FAPI compliant)",
+  "additionalProperties": false,
+  "required": ["auth_req_id", "expires_in"],
+  "properties": {
+    "auth_req_id": {
+      "$id": "/properties/auth_req_id",
+      "type": "string",
+      "description": "This is a unique identifier for the authentication request made by the CIBA Client (third party)",
+      "pattern": "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{12}$",
+      "examples": ["1c266114-a1be-4252-8ad1-04986c5b9ac1"]
+    },
+    "expires_in": {
+      "$id": "/properties/expires_in",
+      "type": "integer",
+      "exclusiveMinimum": 0,
+      "description": "A positive integer value in seconds, indicating the expiration time since the authentication request was received",
+      "examples": [3600]
+    },
+    "interval": {
+      "$id": "/properties/interval",
+      "type": "integer",
+      "minimum": 0,
+      "description": "The number of seconds a client MUST wait between polling requests to the token endpoint",
+      "examples": [10]
+    }
+  }
+}
diff --git a/dist/v2.3.4/ciba-flow/CIBA-login-hint-token-schema.json b/dist/v2.3.4/ciba-flow/CIBA-login-hint-token-schema.json
@@ -0,0 +1,64 @@
+{
+  "definitions": {},
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "http://apicentre.paymentsnz.co.nz/schemas/CIBA-login-hint-schema.json",
+  "type": "object",
+  "title": "The schema for the CIBA request object login_hint_token",
+  "additionalProperties": false,
+  "required": ["subject"],
+  "properties": {
+    "subject": {
+      "$id": "/properties/subject",
+      "type": "object",
+      "title": "Subject of the token",
+      "required": ["subject_type"],
+      "maxProperties": 2,
+      "minProperties": 2,
+      "properties": {
+        "subject_type": {
+          "$id": "/properties/subject/properties/subject_type",
+          "type": "string",
+          "title": "The type of subject hint",
+          "enum": [
+            "phone",
+            "email",
+            "username",
+            "api_provider_token",
+            "third_party_token"
+          ]
+        },
+        "phone": {
+          "$id": "/properties/subject/properties/phone",
+          "type": "string",
+          "title": "The phone of the subject identity to authorise",
+          "examples": ["+64-21-101-1221"]
+        },
+        "email": {
+          "$id": "/properties/subject/properties/email",
+          "type": "string",
+          "title": "The email of the subject identity to authorise",
+          "format": "email",
+          "examples": ["user@example.com"]
+        },
+        "username": {
+          "$id": "/properties/subject/properties/username",
+          "type": "string",
+          "title": "The username of the subject identity to authorise",
+          "examples": ["user.name", "@handle"]
+        },
+        "api_provider_token": {
+          "$id": "/properties/subject/properties/api_provider_token",
+          "type": "string",
+          "title": "A token generated by the customer authentication device",
+          "description": "Uniquely identifies the Customer authentication device and Customer with the API Provider"
+        },
+        "third_party_token": {
+          "$id": "/properties/subject/properties/third_party_token",
+          "type": "string",
+          "title": "A token generated by the third party and registered with the customer authentication device",
+          "pattern": "^[A-Za-z0-9-_]+\\.[A-Za-z0-9-_]+\\.[A-Za-z0-9-_.+/=]*$"
+        }
+      }
+    }
+  }
+}
diff --git a/dist/v2.3.4/ciba-flow/README.md b/dist/v2.3.4/ciba-flow/README.md
@@ -0,0 +1,9 @@
+# CIBA related schemas
+
+The following are CIBA authorisation flow relevant schemas:
+
+* CIBA Authorisation request [schema](./CIBA-authorization-request-object-schema.json)
+* CIBA Authorisation request response [schema](./CIBA-authorization-request-response-schema.json)
+* CIBA `login_hint_token` [schema](./CIBA-login-hint-token-schema.json)
+* CIBA 'ping callback' [schema](./ping-callback-schema.json)
+* The `id_token_hint` (ID token that was previously issued by API provider) [schema](../id-token/id-token-body-schema.json)
diff --git a/dist/v2.3.4/ciba-flow/ping-callback-schema.json b/dist/v2.3.4/ciba-flow/ping-callback-schema.json
@@ -0,0 +1,18 @@
+{
+  "definitions": {},
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "http://apicentre.paymentsnz.co.nz/schemas/ping-callback-schema.json",
+  "type": "object",
+  "title": "The schema for the CIBA callback request",
+  "additionalProperties": false,
+  "required": ["auth_req_id"],
+  "properties": {
+    "auth_req_id": {
+      "$id": "/properties/auth_req_id",
+      "type": "string",
+      "description": "This is a unique identifier for the authentication request made by the CIBA Client (third party)",
+      "pattern": "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{12}$",
+      "examples": ["1c266114-a1be-4252-8ad1-04986c5b9ac1"]
+    }
+  }
+}
diff --git a/dist/v2.3.4/ciba-flow/token-request-response-schema.json b/dist/v2.3.4/ciba-flow/token-request-response-schema.json
@@ -0,0 +1,45 @@
+{
+  "definitions": {},
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "http://apicentre.paymentsnz.co.nz/schemas/token-request-response-schema.json",
+  "type": "object",
+  "title": "The schema for the Open ID Connect token request response",
+  "additionalProperties": false,
+  "required": ["access_token", "token_type", "expires_in", "id_token"],
+  "properties": {
+    "access_token": {
+      "$id": "/properties/access_token",
+      "type": "string",
+      "title": "Access token",
+      "description": "The token to be used on subsequent API requests",
+      "examples": ["G5kXH2wHvUra0sHlDy1iTkDJgsgUO1bN"]
+    },
+    "token_type": {
+      "$id": "/properties/token_type",
+      "type": "string",
+      "title": "The OAuth 2.0 token type",
+      "enum": ["Bearer", "mac"]
+    },
+    "refresh_token": {
+      "$id": "/properties/refresh_token",
+      "type": "string",
+      "title": "Refresh token",
+      "description": "The token to be used to refresh the access token",
+      "examples": ["4bwc0ESC_IAhflf-ACC_vjD_ltc11ne-8gFPfA2Kx16"]
+    },
+    "expires_in": {
+      "$id": "/properties/expires_in",
+      "type": "integer",
+      "exclusiveMinimum": 0,
+      "title": "Access token expiry time",
+      "description": "A positive integer value in seconds, indicating the expiration time since the authentication request was received",
+      "examples": [3600]
+    },
+    "id_token": {
+      "$id": "/properties/id_token",
+      "type": "string",
+      "title": "The ID Token issued to the third party",
+      "pattern": "^[A-Za-z0-9-_]+\\.[A-Za-z0-9-_]+\\.[A-Za-z0-9-_.+/=]*$"
+    }
+  }
+}
diff --git a/dist/v2.3.4/client-authentication/jwt-bearer-auth-schema.json b/dist/v2.3.4/client-authentication/jwt-bearer-auth-schema.json
@@ -0,0 +1,56 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "http://apicentre.paymentsnz.co.nz/schemas/jwt-bearer-auth-schema.json",
+  "type": "object",
+  "title": "The schema used with JWT authentication",
+  "description": "The schema to be used with private_key_jwt or client_secret_jwt as specified by OIDC core draft 1.0",
+  "additionalProperties": true,
+  "required": ["jti", "sub", "iss", "aud", "exp"],
+  "properties": {
+    "jti": {
+      "$id": "#/properties/jti",
+      "type": "string",
+      "description": "The JWT token identifier that must be unique and used only once",
+      "default": "",
+      "examples": ["992267bc-8e1c-4909-b4f4-4f47b652f748"],
+      "pattern": "^(.*)$"
+    },
+    "sub": {
+      "$id": "#/properties/sub",
+      "type": "string",
+      "description": "The JWT subject, which must be client_id",
+      "default": "",
+      "examples": ["38174623762"],
+      "pattern": "^(.*)$"
+    },
+    "iss": {
+      "$id": "#/properties/iss",
+      "type": "string",
+      "description": "The JWT issuer, which must be client_id",
+      "default": "",
+      "examples": ["38174623762"],
+      "pattern": "^(.*)$"
+    },
+    "aud": {
+      "$id": "#/properties/aud",
+      "type": "string",
+      "format": "uri",
+      "description": "The audience for the JWT, which must be the authorisation server token endpoint",
+      "examples": ["http://examplebank.co.nz/oauth2/token"]
+    },
+    "exp": {
+      "$id": "#/properties/exp",
+      "type": "integer",
+      "description": "The time the JWT expires",
+      "default": 0,
+      "examples": [1536165540]
+    },
+    "iat": {
+      "$id": "#/properties/iat",
+      "type": "integer",
+      "description": "The time the JWT was issued by authorisation server",
+      "default": 0,
+      "examples": [1536132708]
+    }
+  }
+}
diff --git a/dist/v2.3.4/common/JOSE-header-schema.json b/dist/v2.3.4/common/JOSE-header-schema.json
@@ -0,0 +1,32 @@
+{
+  "title": "Version 1 of JWT header",
+  "type": "object",
+  "$id": "http://apicentre.paymentsnz.co.nz/schemas/JOSE-header-schema.json",
+  "definitions": {},
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "required": ["alg", "kid"],
+  "properties": {
+    "alg": {
+      "$id": "/properties/alg",
+      "type": "string",
+      "description": "The type of algorithm used to sign the JWT",
+      "examples": ["PS256"],
+      "enum": ["ES256", "PS256"]
+    },
+    "kid": {
+      "$id": "/properties/kid",
+      "type": "string",
+      "description": "The id of a public key or certificate used to sign the content or verify the signature",
+      "examples": ["39cfac46-721f-46d5-8031-df6ae0dcb5f8"],
+      "pattern": "^(.+)$"
+    },
+    "typ": {
+      "$id": "/properties/typ",
+      "type": "string",
+      "description": "Used to denote the media type of the signed token. If included, the value must be 'JWT'.",
+      "enum": ["JWT"],
+      "examples": ["JWT"]
+    }
+  }
+}