{ "openapi": "3.0.0", "info": { "version": "2.0.0.1", "title": "BankID CSC API", "description": "This document contains the API description for BankID CSC API" }, "servers": [ { "url": "https://csc-gw.preprod.esign-stoetest.cloud/csc/v2", "description": "Public testing environment" }, { "url": "https://csc-gw.esign-stoe.cloud/csc/v2", "description": "Production environment" } ], "paths": { "/info": { "post": { "tags": ["info"], "summary": "Returns information about the Remote Service and the list of the API methods implemented and supported by it.", "description": "", "operationId": "info", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/input-info" } } }, "description": "Info request object", "required": true }, "responses": { "200": { "description": "Info response object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/output-info" } } } }, "400": { "description": "Bad Request - Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "invalid_request": { "summary": "Invalid request parameters", "value": { "errorCode": "invalid_request", "errorDescription": "The request is missing a required parameter, includes an invalid parameter value, or is otherwise malformed", "errorReference": "REF123456789" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "internal_error": { "summary": "Internal server error", "value": { "errorCode": "internal_error", "errorDescription": "An internal server error occurred", "errorReference": "REF123456794" } } } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "service_unavailable": { "summary": "Service temporarily unavailable", "value": { "errorCode": "service_unavailable", "errorDescription": "The service is temporarily unavailable", "errorReference": "REF123456795" } } } } } } } } }, "/oauth2/token": { "post": { "tags": ["auth"], "summary": "Returns the access token", "description": "Exchange the authorization code received from the authorization endpoint for an access token. When PKCE is used, the `code_verifier` parameter is required to validate against the `code_challenge` from the authorization request.", "operationId": "oauth2TokenPost", "security": [ { "BankIDClientCredentials": ["esign/csc"] } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/input-oauth2-token" } } }, "description": "Credentials list request object", "required": true }, "responses": { "200": { "description": "OAuth2 token response object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/output-oauth2-token" } } } }, "400": { "description": "Bad Request - Invalid request parameters or PKCE validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/oauth2-error-response" }, "examples": { "invalid_request": { "summary": "Invalid request parameters", "value": { "error": "invalid_request", "error_description": "Missing required parameter: code_verifier" } }, "invalid_grant": { "summary": "Invalid authorization code or PKCE validation failed", "value": { "error": "invalid_grant", "error_description": "The provided authorization code is invalid, expired, or the code_verifier does not match the code_challenge" } } } } } }, "401": { "description": "Unauthorized - Client authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/oauth2-error-response" }, "examples": { "invalid_client": { "summary": "Client authentication failed", "value": { "error": "invalid_client", "error_description": "Client authentication failed" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/oauth2-error-response" }, "examples": { "server_error": { "summary": "Internal server error", "value": { "error": "server_error", "error_description": "The authorization server encountered an unexpected condition that prevented it from fulfilling the request" } } } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/oauth2-error-response" }, "examples": { "temporarily_unavailable": { "summary": "Service temporarily unavailable", "value": { "error": "temporarily_unavailable", "error_description": "The service is temporarily overloaded or under maintenance" } } } } } } } } }, "/credentials/list": { "post": { "tags": ["credentials"], "summary": "Returns the list of credentials associated with a user identifier", "security": [ { "CSCToken": [] } ], "description": "", "operationId": "credentialsList", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/input-credentials-list" } } }, "description": "Credentials list request object", "required": true }, "responses": { "200": { "description": "Credentials list response object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/output-credentials-list" } } } }, "400": { "description": "Bad Request - Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "invalid_request": { "summary": "Invalid request parameters", "value": { "errorCode": "invalid_request", "errorDescription": "The request is missing a required parameter, includes an invalid parameter value, or is otherwise malformed", "errorReference": "REF123456789" } }, "invalid_parameters": { "summary": "Invalid or missing parameters", "value": { "errorCode": "invalid_parameters", "errorDescription": "One or more request parameters are invalid or missing", "errorReference": "REF123456790" } }, "token_already_used": { "summary": "Token already used at this endpoint", "value": { "errorCode": "token_already_used", "errorDescription": "The access token has already been used at this endpoint", "errorReference": "REF123456816" } } } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "authentication_required": { "summary": "Authentication required", "value": { "errorCode": "authentication_required", "errorDescription": "Authentication is required to access this resource", "errorReference": "REF123456791" } }, "invalid_token": { "summary": "Invalid or expired token", "value": { "errorCode": "invalid_token", "errorDescription": "The access token is invalid, expired, or malformed", "errorReference": "REF123456792" } } } } } }, "403": { "description": "Forbidden - Insufficient permissions or scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "insufficient_scope": { "summary": "Insufficient scope", "value": { "errorCode": "insufficient_scope", "errorDescription": "The access token does not have the required scope", "errorReference": "REF123456793" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "internal_error": { "summary": "Internal server error", "value": { "errorCode": "internal_error", "errorDescription": "An internal server error occurred", "errorReference": "REF123456794" } }, "csc_service_error": { "summary": "CSC service communication error", "value": { "errorCode": "csc_service_error", "errorDescription": "Error occurred while communicating with the CSC service", "errorReference": "REF123456796" } } } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "service_unavailable": { "summary": "Service temporarily unavailable", "value": { "errorCode": "service_unavailable", "errorDescription": "The service is temporarily unavailable", "errorReference": "REF123456795" } }, "csc_user_keys_limit": { "summary": "Key generation limit reached", "value": { "errorCode": "csc_user_keys_limit", "errorDescription": "The signing backend key generation limit has been reached. Retry after a short delay", "errorReference": "REF123456817" } } } } } } } } }, "/credentials/info": { "post": { "tags": [ "credentials" ], "summary": "Retrieve the credential and return the main identity information and the public key certificate or the certificate chain associated to it.", "x-original-summary": "Retrieve the credential and return the main identity information and the public key certificate or the certificate chain associated to it.", "security": [ { "CSCToken": [] } ], "description": "Retrieve the credential and return the main identity information and the public key certificate or the certificate chain associated to it. If the credential is authorized for remote signing, the information about the authorization mechanism is also returned.", "x-original-description": "", "operationId": "credentialsInfo", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/input-credentials-info" } } }, "description": "Credentials info request object", "required": true }, "responses": { "200": { "description": "Credentials info response object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/output-credentials-info" } } } }, "400": { "description": "Bad Request - Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "invalid_request": { "summary": "Invalid request parameters", "value": { "errorCode": "invalid_request", "errorDescription": "The request is missing a required parameter, includes an invalid parameter value, or is otherwise malformed", "errorReference": "REF123456789" } }, "invalid_credential_id": { "summary": "Invalid credential ID", "value": { "errorCode": "invalid_credential_id", "errorDescription": "The credential ID is invalid or not found", "errorReference": "REF123456801" } } } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "authentication_required": { "summary": "Authentication required", "value": { "errorCode": "authentication_required", "errorDescription": "Authentication is required to access this resource", "errorReference": "REF123456791" } }, "invalid_token": { "summary": "Invalid or expired token", "value": { "errorCode": "invalid_token", "errorDescription": "The access token is invalid, expired, or malformed", "errorReference": "REF123456792" } } } } } }, "403": { "description": "Forbidden - Insufficient permissions or credential issues", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "insufficient_scope": { "summary": "Insufficient scope", "value": { "errorCode": "insufficient_scope", "errorDescription": "The access token does not have the required scope", "errorReference": "REF123456793" } }, "certificate_expired": { "summary": "Certificate expired", "value": { "errorCode": "certificate_expired", "errorDescription": "The certificate has expired", "errorReference": "REF123456802" } }, "certificate_revoked": { "summary": "Certificate revoked", "value": { "errorCode": "certificate_revoked", "errorDescription": "The certificate has been revoked", "errorReference": "REF123456803" } } } } } }, "404": { "description": "Not Found - Credential or certificate not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "credential_not_found": { "summary": "Credential not found", "value": { "errorCode": "credential_not_found", "errorDescription": "The specified credential was not found", "errorReference": "REF123456804" } }, "certificate_not_found": { "summary": "Certificate not found", "value": { "errorCode": "certificate_not_found", "errorDescription": "The certificate was not found", "errorReference": "REF123456805" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "internal_error": { "summary": "Internal server error", "value": { "errorCode": "internal_error", "errorDescription": "An internal server error occurred", "errorReference": "REF123456794" } }, "csc_service_error": { "summary": "CSC service communication error", "value": { "errorCode": "csc_service_error", "errorDescription": "Error occurred while communicating with the CSC service", "errorReference": "REF123456796" } } } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "service_unavailable": { "summary": "Service temporarily unavailable", "value": { "errorCode": "service_unavailable", "errorDescription": "The service is temporarily unavailable", "errorReference": "REF123456795" } } } } } } } } }, "/oauth2/authorize": { "get": { "summary": "Authorize OAuth2 request", "description": "Initiates user authentication and signature consent. Redirects to `redirect_uri` with `code` and `state`. PKCE: `code_challenge` (S256) required and must match `code_verifier` at /oauth2/token. scope optional (default `esign/csc`); add `esign/nnin` to include NNIN in the certificate.", "operationId": "oauth2Authorize", "tags": ["auth"], "parameters": [ { "$ref": "#/components/parameters/ResponseType" }, { "$ref": "#/components/parameters/ClientId" }, { "$ref": "#/components/parameters/RedirectUri" }, { "$ref": "#/components/parameters/Scope" }, { "$ref": "#/components/parameters/CodeChallenge" }, { "$ref": "#/components/parameters/CodeChallengeMethod" }, { "$ref": "#/components/parameters/Lang" }, { "$ref": "#/components/parameters/State" } ], "responses": { "302": { "description": "After an attempted authorization, the authorization server will redirect the user-agent back to the specified redirect_uri with query parameters.", "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/output-oauth2-authorize" }, "examples": { "successExample": { "summary": "Success", "value": { "code": "FhkXf9P269L8g", "state": "12345678" } }, "errorExample": { "summary": "Error", "value": { "state": "12345678", "error": "access_denied", "error_description": "User denied the authorization request.", "error_uri": "https://example.com/error-info" } } } } } } } } }, "/credentials/authorize": { "post": { "tags": ["credentials"], "summary": "Authorize the access to the credential for remote signing, according to the authorization mechanisms associated to it.", "security": [ { "CSCToken": [] } ], "description": "", "operationId": "credentialsAuthorize", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/input-credentials-authorize" } } }, "description": "Credentials authorize request object", "required": true }, "responses": { "200": { "description": "Credentials authorize response object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/output-credentials-authorize" } } } }, "400": { "description": "Bad Request - Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "invalid_request": { "summary": "Invalid request parameters", "value": { "errorCode": "invalid_request", "errorDescription": "The request is missing a required parameter, includes an invalid parameter value, or is otherwise malformed", "errorReference": "REF123456789" } }, "invalid_credential_id": { "summary": "Invalid credential ID", "value": { "errorCode": "invalid_credential_id", "errorDescription": "The credential ID is invalid or not found", "errorReference": "REF123456801" } }, "invalid_sad": { "summary": "Invalid SAD", "value": { "errorCode": "invalid_sad", "errorDescription": "The Signature Activation Data (SAD) is invalid", "errorReference": "REF123456806" } }, "token_already_used": { "summary": "Token already used at this endpoint", "value": { "errorCode": "token_already_used", "errorDescription": "The access token has already been used at this endpoint", "errorReference": "REF123456816" } } } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "authentication_required": { "summary": "Authentication required", "value": { "errorCode": "authentication_required", "errorDescription": "Authentication is required to access this resource", "errorReference": "REF123456791" } }, "invalid_token": { "summary": "Invalid or expired token", "value": { "errorCode": "invalid_token", "errorDescription": "The access token is invalid, expired, or malformed", "errorReference": "REF123456792" } } } } } }, "403": { "description": "Forbidden - Insufficient permissions or credential issues", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "insufficient_scope": { "summary": "Insufficient scope", "value": { "errorCode": "insufficient_scope", "errorDescription": "The access token does not have the required scope", "errorReference": "REF123456793" } }, "credential_locked": { "summary": "Credential locked", "value": { "errorCode": "credential_locked", "errorDescription": "The credential is locked or suspended", "errorReference": "REF123456807" } }, "credential_expired": { "summary": "Credential expired", "value": { "errorCode": "credential_expired", "errorDescription": "The credential has expired", "errorReference": "REF123456808" } } } } } }, "404": { "description": "Not Found - Credential not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "credential_not_found": { "summary": "Credential not found", "value": { "errorCode": "credential_not_found", "errorDescription": "The specified credential was not found", "errorReference": "REF123456804" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "internal_error": { "summary": "Internal server error", "value": { "errorCode": "internal_error", "errorDescription": "An internal server error occurred", "errorReference": "REF123456794" } }, "csc_service_error": { "summary": "CSC service communication error", "value": { "errorCode": "csc_service_error", "errorDescription": "Error occurred while communicating with the CSC service", "errorReference": "REF123456796" } } } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "service_unavailable": { "summary": "Service temporarily unavailable", "value": { "errorCode": "service_unavailable", "errorDescription": "The service is temporarily unavailable", "errorReference": "REF123456795" } } } } } } } } }, "/signatures/signHash": { "post": { "tags": ["signatures"], "summary": "Calculate the remote digital signature of one or multiple hash values provided as an input.", "security": [ { "CSCToken": [] } ], "description": "", "operationId": "signaturesSignhash", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/input-signatures-signhash" } } }, "description": "Sign hash request object", "required": true }, "responses": { "200": { "description": "Sign hash response object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/output-signatures-signhash" } } } }, "400": { "description": "Bad Request - Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "invalid_request": { "summary": "Invalid request parameters", "value": { "errorCode": "invalid_request", "errorDescription": "The request is missing a required parameter, includes an invalid parameter value, or is otherwise malformed", "errorReference": "REF123456789" } }, "invalid_credential_id": { "summary": "Invalid credential ID", "value": { "errorCode": "invalid_credential_id", "errorDescription": "The credential ID is invalid or not found", "errorReference": "REF123456801" } }, "invalid_sad": { "summary": "Invalid SAD", "value": { "errorCode": "invalid_sad", "errorDescription": "The Signature Activation Data (SAD) is invalid", "errorReference": "REF123456806" } }, "hash_mismatch": { "summary": "Hash value mismatch", "value": { "errorCode": "hash_mismatch", "errorDescription": "The hash value does not match the expected value", "errorReference": "REF123456809" } }, "invalid_hash_algorithm": { "summary": "Invalid hash algorithm", "value": { "errorCode": "invalid_hash_algorithm", "errorDescription": "The hash algorithm is not supported", "errorReference": "REF123456810" } }, "invalid_signature_format": { "summary": "Invalid signature format", "value": { "errorCode": "invalid_signature_format", "errorDescription": "The signature format or algorithm is not supported", "errorReference": "REF123456811" } }, "token_already_used": { "summary": "Token already used at this endpoint", "value": { "errorCode": "token_already_used", "errorDescription": "The access token has already been used at this endpoint", "errorReference": "REF123456816" } } } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "authentication_required": { "summary": "Authentication required", "value": { "errorCode": "authentication_required", "errorDescription": "Authentication is required to access this resource", "errorReference": "REF123456791" } }, "invalid_token": { "summary": "Invalid or expired token", "value": { "errorCode": "invalid_token", "errorDescription": "The access token is invalid, expired, or malformed", "errorReference": "REF123456792" } } } } } }, "403": { "description": "Forbidden - Insufficient permissions or signing issues", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "insufficient_scope": { "summary": "Insufficient scope", "value": { "errorCode": "insufficient_scope", "errorDescription": "The access token does not have the required scope", "errorReference": "REF123456793" } }, "signing_limit_exceeded": { "summary": "Signing limit exceeded", "value": { "errorCode": "signing_limit_exceeded", "errorDescription": "The signing limit has been exceeded", "errorReference": "REF123456812" } }, "credential_locked": { "summary": "Credential locked", "value": { "errorCode": "credential_locked", "errorDescription": "The credential is locked or suspended", "errorReference": "REF123456807" } } } } } }, "404": { "description": "Not Found - Credential not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "credential_not_found": { "summary": "Credential not found", "value": { "errorCode": "credential_not_found", "errorDescription": "The specified credential was not found", "errorReference": "REF123456804" } } } } } }, "413": { "description": "Payload Too Large - Document too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "document_too_large": { "summary": "Document too large", "value": { "errorCode": "document_too_large", "errorDescription": "The document size exceeds the maximum allowed limit", "errorReference": "REF123456813" } } } } } }, "422": { "description": "Unprocessable Entity - Signature validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "signature_validation_failed": { "summary": "Signature validation failed", "value": { "errorCode": "signature_validation_failed", "errorDescription": "The signature validation failed", "errorReference": "REF123456814" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "internal_error": { "summary": "Internal server error", "value": { "errorCode": "internal_error", "errorDescription": "An internal server error occurred", "errorReference": "REF123456794" } }, "csc_service_error": { "summary": "CSC service communication error", "value": { "errorCode": "csc_service_error", "errorDescription": "Error occurred while communicating with the CSC service", "errorReference": "REF123456796" } } } } } }, "501": { "description": "Not Implemented - Unsupported operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "unsupported_operation": { "summary": "Unsupported operation", "value": { "errorCode": "unsupported_operation", "errorDescription": "The operation is not supported for this credential type", "errorReference": "REF123456815" } } } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csc-error-response" }, "examples": { "service_unavailable": { "summary": "Service temporarily unavailable", "value": { "errorCode": "service_unavailable", "errorDescription": "The service is temporarily unavailable", "errorReference": "REF123456795" } } } } } } } } } }, "components": { "parameters": { "ResponseType": { "name": "response_type", "in": "query", "description": "OAuth2 response type (e.g., `code` for authorization code).", "required": true, "schema": { "type": "string", "description": "OAuth2 response type." } }, "ClientId": { "name": "client_id", "in": "query", "description": "The client identifier issued to the client.", "required": true, "schema": { "type": "string", "description": "Client ID." } }, "RedirectUri": { "name": "redirect_uri", "in": "query", "description": "The URI to redirect to after authorization.", "required": true, "schema": { "type": "string", "description": "Redirect URI." } }, "Scope": { "name": "scope", "in": "query", "description": "Space-delimited list of requested scopes.", "required": false, "schema": { "type": "string", "description": "Space-delimited list of scopes.", "default": "esign/csc" }, "example": "esign/csc esign/nnin" }, "CodeChallenge": { "name": "code_challenge", "in": "query", "description": "PKCE code challenge.", "required": true, "schema": { "type": "string", "description": "PKCE code challenge." } }, "CodeChallengeMethod": { "name": "code_challenge_method", "in": "query", "description": "PKCE code challenge method.", "required": true, "schema": { "type": "string", "description": "PKCE code challenge method.", "enum": ["S256"], "default": "S256" } }, "Lang": { "name": "lang", "in": "query", "description": "Language preference for the UI. Supported values are nb (Norwegian Bokmål), nn (Norwegian Nynorsk) or en (English).", "required": false, "schema": { "type": "string", "description": "Request a preferred language according to RFC 5646 with only the primary language subtag.", "default": "nb" } }, "State": { "name": "state", "in": "query", "description": "An opaque value to maintain state between the request and callback.", "required": false, "schema": { "type": "string", "description": "State parameter to maintain request context." } } }, "securitySchemes": { "BankIDClientCredentials": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://auth.current.bankid.no/auth/realms/current/protocol/openid-connect/token", "scopes": { "esign/csc": "Grants CSC access", "esign/nnin": "Grants NNIN access" } } } }, "CSCToken": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The token is obtained from the `/oauth2/token` endpoint." } }, "schemas": { "input-oauth2-authorize": { "type": "object", "properties": { "response_type": { "type": "string", "description": "OAuth2 response type.", "enum": ["code"] }, "client_id": { "type": "string", "description": "Client ID." }, "redirect_uri": { "type": "string", "description": "Redirect URI." }, "scope": { "type": "string", "description": "Space-delimited list of scopes." }, "code_challenge": { "type": "string", "description": "PKCE code challenge." }, "code_challenge_method": { "type": "string", "description": "PKCE code challenge method. Must be 'S256' for SHA256 hashing.", "enum": ["S256"], "default": "S256" }, "lang": { "$ref": "#/components/schemas/lang" }, "state": { "type": "string", "description": "State parameter to maintain request context." }, "clientData": { "$ref": "#/components/schemas/clientData" } } }, "output-oauth2-authorize": { "type": "object", "required": ["state"], "properties": { "code": { "type": "string", "description": "The authorization code generated by the authorization server.", "example": "FhkXf9P269L8g" }, "state": { "type": "string", "description": "The state parameter to maintain request context.", "example": "12345678" }, "error": { "type": "string", "description": "Error code, returned only if there is an error.", "enum": [ "invalid_request", "access_denied", "unsupported_response_type", "invalid_scope", "server_error", "temporarily_unavailable" ] }, "error_description": { "type": "string", "description": "A human-readable description of the error.", "example": "The requested scope is invalid." }, "error_uri": { "type": "string", "description": "A URI that provides more details about the error. Not yet implemented", "example": "https://example.com/error-info" } } }, "access_token": { "type": "string", "description": "The short-lived service access token used to authenticate the subsequent API requests within the same session." }, "token_type": { "type": "string", "description": "Type of the returned token." }, "authMode": { "type": "string", "description": "Specifies one of the authorization modes", "pattern": "^(implicit|explicit|oauth2code|oauth2token)$" }, "authType": { "type": "array", "description": "Specifies one or more values corresponding to the authentication mechanisms supported by the Remote Service", "items": { "type": "string", "description": "Specifies one or more values corresponding to the authentication mechanisms supported by the Remote Service", "pattern": "^(external|TLS|basic|digest|oauth2code|oauth2implicit|oauth2client)$" } }, "cert": { "type": "object", "description": "Contains information about the signature certificate", "properties": { "status": { "type": "string", "description": "The Status Schema", "pattern": "^(valid|expired|revoked|suspended)$" }, "certificates": { "type": "array", "description": "Contains one or more Base64-encoded X.509v3 certificates from the certificate chain", "items": { "type": "string", "description": "A single Base64-encoded X.509v3 certificate" } }, "issuerDN": { "type": "string", "description": "The Issuer Subject Distinguished Name from the X.509v3 end entity certificate in printable string format" }, "serialNumber": { "type": "string", "description": "The Serial Number from the X.509v3 certificate in hex encoded format" }, "subjectDN": { "type": "string", "description": "The Distinguished Name from the X.509v3 certificate in printable string format" }, "validFrom": { "type": "string", "description": "The validity start date from the X.509v3 certificate in printable string format" }, "validTo": { "type": "string", "description": "The validity end date from the X.509v3 certificate in printable string format" } } }, "certificates": { "type": "string", "description": "The Certificates Schema", "pattern": "^(none|single|chain)$" }, "certInfo": { "type": "boolean", "description": "Specifies if the information on the end entity certificate shall be returned as printable strings" }, "clientData": { "type": "string", "description": "Arbitrary data from the Signature Application" }, "code_verifier": { "type": "string", "description": "The PKCE code verifier used to validate the code_challenge from the authorization request. A cryptographically random string using the characters [A-Z] / [a-z] / [0-9] / '-' / '.' / '_' / '~', between 43 and 128 characters long.", "minLength": 43, "maxLength": 128, "pattern": "^[A-Za-z0-9._~-]+$" }, "credentialID": { "type": "string", "description": "The identifier associated to the credential" }, "credentialIDs": { "type": "array", "description": "One or more credentialID associated with the provided or implicit userID", "items": { "type": "string", "description": "The credentialIDs Schema" } }, "credentialInfo": { "type": "boolean" }, "description": { "type": "string", "description": "Contains a free form description of the authorization transaction in the lang language" }, "expires_in": { "type": "number", "description": "The lifetime in seconds of the service access token." }, "expiresIn": { "type": "number", "description": "The lifetime in seconds of the service access token" }, "hashes": { "type": "array", "description": "One or more Base64-encoded hash values to be signed", "minItems": 1, "maxItems": 50, "items": { "type": "string", "description": "Single Base64-encoded hash value to be signed" } }, "hashAlgorithmOID": { "type": "string", "description": "Specifies the OID of the algorithm used to calculate the hash value(s). Only 2.16.840.1.101.3.4.2.1 is supported (SHA-256)." }, "hashTBS": { "type": "string", "description": "The Base64-encoded hash value to be time stamped" }, "key": { "type": "object", "description": "Information about the key", "required": ["status", "algo", "len"], "properties": { "status": { "type": "string", "description": "The status of enablement of the signing key of the credential", "pattern": "^(enabled|disabled)$" }, "algo": { "type": "array", "description": "The list of OIDs of the supported key algorithms", "items": { "type": "string", "description": "A single OID" } }, "len": { "type": "integer", "description": "The length of the cryptographic key in bits" }, "curve": { "type": "string", "description": "The OID of the ECDSA curve" } } }, "lang": { "type": "string", "description": "Request a preferred language according to RFC 3066" }, "logo": { "type": "string", "description": "The URI of the image file containing the logo of the Remote Service which shall be published online" }, "maxResults": { "type": "number", "description": "Maximum number of items to return" }, "methods": { "type": "array", "description": "Specifies the list of names of all the API methods", "items": { "type": "string", "description": "The Method Name" } }, "multisign": { "type": "integer", "description": "Specifies if the credential supports multiple signatures to be created with a single authorization request" }, "name": { "type": "string", "description": "The commercial name of the Remote Service" }, "nonce": { "type": "string", "description": "Specifies a large random number with a high probability that it is generated by the Signature Application only once" }, "numSignatures": { "type": "integer", "description": "The number of signatures to authorize", "minimum": 1, "maximum": 50 }, "oauth2": { "type": "string", "description": "Specifies the complete URI of the OAuth 2.0 service authorization endpoint provided by the Remote Service" }, "pageToken": { "type": "string", "description": "The page token for the new page of items" }, "refresh_token": { "type": "string", "description": "The long-lived refresh token returned from the previous HTTP Basic Authentication" }, "region": { "type": "string", "description": "The ISO 3166-1 Alpha-2 code of the Country where the Remote Service provider is established" }, "rememberMe": { "type": "boolean", "description": "option that the user may activate during the authentication phase to stay signed in" }, "SAD": { "type": "string", "description": "The Signature Activation Data to provide as input to the signatures/signHash method." }, "SCAL": { "type": "string", "description": "Specifies the Sole Control Assurance Level required by the credential, as defined in CEN EN 419 241-1", "pattern": "^(1|2)$" }, "credentialInfoItem": { "type": "object", "description": "Information about a single credential", "required": ["credentialID"], "properties": { "credentialID": { "$ref": "#/components/schemas/credentialID" }, "description": { "type": "string", "description": "A free form description of the credential in the lang language. Maximum size is 255 characters." }, "signatureQualifier": { "type": "string", "description": "Identifier qualifying the type of signature this credential is suitable for" }, "key": { "$ref": "#/components/schemas/key" }, "cert": { "$ref": "#/components/schemas/cert" }, "auth": { "$ref": "#/components/schemas/authInfo" }, "SCAL": { "$ref": "#/components/schemas/SCAL" }, "multisign": { "$ref": "#/components/schemas/multisign" }, "lang": { "$ref": "#/components/schemas/lang" } } }, "authInfo": { "type": "object", "description": "Information about the authorization mechanism", "required": ["mode"], "properties": { "mode": { "type": "string", "description": "Specifies one of the authorization modes", "enum": ["explicit", "oauth2code"] }, "expression": { "type": "string", "description": "An expression defining the combination of authentication objects required to authorize usage of the private key" }, "objects": { "type": "array", "description": "The authentication object types available for this credential", "items": { "$ref": "#/components/schemas/authObject" } } } }, "authObject": { "type": "object", "description": "Authentication object type", "properties": { "type": { "type": "string", "description": "The type of authentication object" }, "id": { "type": "string", "description": "The identifier of the authentication object" }, "format": { "type": "string", "description": "The format of the authentication object" }, "label": { "type": "string", "description": "The label of the authentication object" }, "description": { "type": "string", "description": "The description of the authentication object" }, "generator": { "type": "string", "description": "The generator type (e.g., totp)" } } }, "signAlgo": { "type": "string", "description": "Specifies the OID of the algorithm to use for signing. Only 1.2.840.10045.4.3.2 is supported (ecdsa-with-SHA256)." }, "signAlgoParams": { "type": "string", "description": "Specifies the Base64-encoded of DER-encoded ASN.1 signature parameters" }, "signatures": { "type": "array", "description": "Array of Base64-encoded signed hashes", "items": { "type": "string", "description": "One Base64-encoded signed hashes" } }, "timestamp": { "type": "string", "description": "The Base64-encoded time-stamp token as defined in RFC 3161 as updated by RFC 5816" }, "specs": { "type": "string", "description": "The version of this specification implemented by the provider" }, "token": { "type": "string", "description": "The token that the Signature Application wants to get revoked." }, "token_type_hint": { "type": "string", "description": "Specifies an optional hint about the type of the token submitted for revocation." }, "userID": { "type": "string", "description": "The user identifier associated to the user identity" }, "input-info": { "type": "object", "description": "Input parameters for info method", "properties": { "lang": { "$ref": "#/components/schemas/lang" } }, "example": { "lang": "en" } }, "input-oauth2-token": { "type": "object", "description": "Input parameters for oauth2/token method", "required": ["grant_type", "code", "redirect_uri", "code_verifier"], "properties": { "grant_type": { "type": "string", "description": "The grant type", "enum": ["authorization_code"] }, "code": { "type": "string", "description": "The authorize code" }, "redirect_uri": { "type": "string", "description": "The client redirect_uri" }, "code_verifier": { "$ref": "#/components/schemas/code_verifier" } }, "example": { "grant_type": "authorization_code", "code": "12345678", "redirect_uri": "https://example.com/callback", "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk" } }, "input-credentials-list": { "type": "object", "description": "Input parameters for credentials/list method", "properties": { "credentialInfo": { "$ref": "#/components/schemas/credentialInfo" }, "certificates": { "$ref": "#/components/schemas/certificates" }, "certInfo": { "$ref": "#/components/schemas/certInfo" }, "authInfo": { "type": "boolean", "description": "Request to return various parameters containing information on the authorization mechanisms supported by the corresponding credential", "default": false }, "onlyValid": { "type": "boolean", "description": "Request to return only credentials usable to create a valid signature. This service only returns valid credentials.", "default": true }, "lang": { "$ref": "#/components/schemas/lang" }, "clientData": { "$ref": "#/components/schemas/clientData" } }, "example": { "credentialInfo": true, "certificates": "single", "certInfo": true, "authInfo": true } }, "input-credentials-info": { "type": "object", "description": "Input parameters for credentials/info method", "required": ["credentialID"], "properties": { "credentialID": { "$ref": "#/components/schemas/credentialID" }, "certificates": { "$ref": "#/components/schemas/certificates" }, "certInfo": { "$ref": "#/components/schemas/certInfo" }, "lang": { "$ref": "#/components/schemas/lang" }, "clientData": { "$ref": "#/components/schemas/clientData" }, "authInfo": { "type": "boolean", "description": "Specifies if the information on the authorization mechanism shall be returned" } }, "example": { "credentialID": "b936b853-bb99-439c-94a3-94e552d6d5af", "certificates": "chain", "certInfo": true, "authInfo": true } }, "input-credentials-authorize": { "type": "object", "description": "Input parameters for credentials/authorize method", "required": [ "credentialID", "numSignatures", "hashes", "hashAlgorithmOID" ], "properties": { "credentialID": { "$ref": "#/components/schemas/credentialID" }, "numSignatures": { "$ref": "#/components/schemas/numSignatures" }, "hashes": { "$ref": "#/components/schemas/hashes" }, "hashAlgorithmOID": { "$ref": "#/components/schemas/hashAlgorithmOID" }, "clientData": { "$ref": "#/components/schemas/clientData" } }, "example": { "credentialID": "b936b853-bb99-439c-94a3-94e552d6d5af", "numSignatures": 2, "hashes": [ "sTOgwOm+474gFj0q0x1iSNspKqbcse4IeiqlDg/HWuI=", "c1RPZ3dPbSs0NzRnRmowcTB4MWlTTnNwS3FiY3NlNEllaXFsRGcvSFd1ST0=" ], "clientData": "some data", "hashAlgorithmOID": "2.16.840.1.101.3.4.2.1" } }, "input-signatures-signhash": { "type": "object", "description": "Input parameters for signatures/signHash method", "required": [ "credentialID", "SAD", "hashes", "signAlgo", "hashAlgorithmOID" ], "properties": { "credentialID": { "$ref": "#/components/schemas/credentialID" }, "SAD": { "$ref": "#/components/schemas/SAD" }, "hashes": { "$ref": "#/components/schemas/hashes" }, "hashAlgorithmOID": { "$ref": "#/components/schemas/hashAlgorithmOID" }, "signAlgo": { "$ref": "#/components/schemas/signAlgo" }, "signAlgoParams": { "$ref": "#/components/schemas/signAlgoParams" }, "clientData": { "$ref": "#/components/schemas/clientData" } }, "example": { "credentialID": "b936b853-bb99-439c-94a3-94e552d6d5af", "SAD": "_TiHRG-bAH3XlFQZ3ndFhkXf9P24/CKN69L8gdSYp5_pw", "hashes": [ "sTOgwOm+474gFj0q0x1iSNspKqbcse4IeiqlDg/HWuI=", "c1RPZ3dPbSs0NzRnRmowcTB4MWlTTnNwS3FiY3NlNEllaXFsRGcvSFd1ST0=" ], "hashAlgorithmOID": "2.16.840.1.101.3.4.2.1", "signAlgo": "1.2.840.10045.4.3.2" } }, "output-info": { "type": "object", "description": "Output parameters for info method", "required": [ "specs", "name", "logo", "region", "lang", "description", "authType", "methods", "signAlgorithms", "signature_formats", "conformance_levels" ], "properties": { "specs": { "$ref": "#/components/schemas/specs" }, "name": { "$ref": "#/components/schemas/name" }, "logo": { "$ref": "#/components/schemas/logo" }, "region": { "$ref": "#/components/schemas/region" }, "lang": { "$ref": "#/components/schemas/lang" }, "description": { "type": "string", "description": "A free form description of the remote service in the lang language. The maximum size of the string is 255 characters.", "maxLength": 255 }, "authType": { "$ref": "#/components/schemas/authType" }, "oauth2": { "$ref": "#/components/schemas/oauth2" }, "oauth2Issuer": { "type": "string", "description": "The issuer URL of the OAuth 2.0 authorization server as defined in IETF RFC 8414" }, "asynchronousOperationMode": { "type": "boolean", "description": "This parameter shall be true if the remote signing server supports also asynchronous signature mechanism. The default value is false." }, "methods": { "$ref": "#/components/schemas/methods" }, "validationInfo": { "type": "boolean", "description": "This parameter SHALL be true if the remote signing server supports the validationInfo response parameter of the method signatures/signDoc in not mandatory cases." }, "signAlgorithms": { "type": "object", "description": "Object including one or more signature algorithms supported by the RSSP", "required": ["algos"], "properties": { "algos": { "type": "array", "items": { "type": "string" }, "description": "The list of signature algorithms supported by the RSSP" }, "algoParams": { "type": "array", "items": { "type": "string" }, "description": "The list of eventual signature parameters" } } }, "signature_formats": { "type": "object", "description": "Object including one or more signature formats supported by the RSSP", "required": ["formats"], "properties": { "formats": { "type": "array", "items": { "type": "string" }, "description": "The list of signature formats supported by the RSSP" }, "envelope_properties": { "type": "array", "items": { "type": "array", "items": { "type": "string" } }, "description": "The list of the properties concerning the signed envelope" } } }, "conformance_levels": { "type": "array", "items": { "type": "string" }, "description": "The list of names of all signature conformance levels supported by the RSSP" } }, "example": { "specs": "2.0.0.2", "description": "This is the CSC API of the ACME Trust Services", "name": "ACME Trust Services", "logo": "https://service.domain.org/images/logo.png", "region": "IT", "lang": "en", "authType": ["basic", "oauth2code", "oauth2implicit"], "oauth2": "https://www.domain.org/", "methods": [ "auth/login", "auth/revoke", "credentials/list", "credentials/info", "credentials/authorize", "signatures/signhash" ], "signAlgorithms": { "algos": [ "1.2.840.10045.4.3.2", "1.2.840.113549.1.1.1", "1.2.840.113549.1.1.10" ] }, "signature_formats": { "formats": ["C", "X", "P"], "envelope_properties": [ ["Detached", "Attached", "Parallel"], ["Enveloped", "Enveloping", "Detached"], ["Certification", "Revision"] ] }, "conformance_levels": ["Ades-B-B", "Ades-B-T"] } }, "output-oauth2-token": { "type": "object", "description": "Output parameters for oauth2/token method", "required": ["access_token"], "properties": { "access_token": { "$ref": "#/components/schemas/access_token" }, "expires_in": { "$ref": "#/components/schemas/expires_in" }, "token_type": { "$ref": "#/components/schemas/token_type" }, "refresh_token": { "$ref": "#/components/schemas/refresh_token" } } }, "oauth2-error-response": { "type": "object", "description": "OAuth2 error response as defined in RFC 6749", "required": ["error"], "properties": { "error": { "type": "string", "description": "A single ASCII error code", "enum": [ "invalid_request", "invalid_client", "invalid_grant", "unauthorized_client", "unsupported_grant_type", "invalid_scope", "server_error", "temporarily_unavailable" ] }, "error_description": { "type": "string", "description": "Human-readable ASCII text providing additional information about the error" }, "error_uri": { "type": "string", "description": "A URI identifying a human-readable web page with information about the error" } }, "example": { "error": "invalid_grant", "error_description": "The provided authorization code is invalid, expired, or the code_verifier does not match the code_challenge" } }, "csc-error-response": { "type": "object", "description": "CSC API error response as defined in CSC API v2.0.0.2 specification", "required": ["errorCode", "errorDescription"], "properties": { "errorCode": { "type": "string", "description": "A single ASCII error code as defined in the CSC specification", "enum": [ "invalid_request", "invalid_parameters", "invalid_scope", "invalid_transaction_id", "invalid_credential_id", "invalid_signature_format", "invalid_hash_algorithm", "invalid_sad", "authentication_required", "insufficient_scope", "invalid_token", "token_revoked", "certificate_expired", "certificate_revoked", "certificate_not_found", "credential_not_found", "credential_locked", "credential_expired", "signing_limit_exceeded", "signature_validation_failed", "hash_mismatch", "document_too_large", "unsupported_operation", "csc_service_error", "csc_service_timeout", "csc_service_unavailable", "certificate_creation_failed", "token_already_used", "csc_user_keys_limit", "service_unavailable", "maintenance_mode", "internal_error", "database_error", "configuration_error" ] }, "errorDescription": { "type": "string", "description": "Human-readable ASCII text providing additional information about the error" }, "errorReference": { "type": "string", "description": "A unique reference identifier for this specific error occurrence, used for support and troubleshooting", "pattern": "^REF[0-9]{9}$" } }, "example": { "errorCode": "invalid_request", "errorDescription": "The request is missing a required parameter, includes an invalid parameter value, or is otherwise malformed", "errorReference": "REF123456789" } }, "output-credentials-list": { "type": "object", "description": "Output parameters for credentials/list method", "required": ["credentialIDs"], "properties": { "credentialIDs": { "$ref": "#/components/schemas/credentialIDs" }, "credentialInfos": { "type": "array", "description": "The contents of credentialInfo objects. If the credentialInfo parameter is not true, this value SHALL NOT be returned.", "items": { "$ref": "#/components/schemas/credentialInfoItem" } }, "onlyValid": { "type": "boolean", "description": "This value SHALL be returned true when the input parameter onlyValid was true, and the RSSP supports this feature" }, "lang": { "$ref": "#/components/schemas/lang" } }, "example": { "credentialIDs": ["cb4c61e3-87f5-4eb4-a1a1-dfbd5830450c"], "onlyValid": false, "credentialInfos": [ { "credentialID": "cb4c61e3-87f5-4eb4-a1a1-dfbd5830450c", "key": { "status": "enabled", "algo": ["1.2.840.10045.2.1"], "len": 256, "curve": "1.2.840.10045.3.1.7" }, "cert": { "status": "valid", "certificates": ["MIIESTCCA8+gAwIBAgIQFc…"], "issuerDN": "C=NO,O=BankID BankAxept AS,OU=BankID,CN=CA 1a Devlab", "serialNumber": "28953693779690026433867899813045097094", "subjectDN": "givenName=Name,CN=Nameson, Name,SN=Poclord,serialNumber=UN:NO-9578-5100-Eqt7hD6ia8QjkLbGgpteVoG8k2LZMX2io6LvAGXkPP8", "validFrom": "20250512121052+0000", "validTo": "20250512122552+0000" }, "auth": { "mode": "explicit", "expression": "OUT_OF_BAND_IDP", "objects": [ { "type": "PasswordOOB", "id": "OUT_OF_BAND_IDP", "label": "Out of the band (IdP)", "description": "Pre authorization will be used for credential authorization" } ] }, "SCAL": "2", "multisign": 2147483647 } ] } }, "output-credentials-info": { "type": "object", "description": "Output parameters for credentials/info method", "required": ["key", "cert", "multisign", "SCAL"], "properties": { "description": { "$ref": "#/components/schemas/description" }, "certificates": { "$ref": "#/components/schemas/certificates" }, "key": { "$ref": "#/components/schemas/key" }, "cert": { "$ref": "#/components/schemas/cert" }, "SCAL": { "$ref": "#/components/schemas/SCAL" }, "multisign": { "$ref": "#/components/schemas/multisign" }, "lang": { "$ref": "#/components/schemas/lang" }, "auth": { "$ref": "#/components/schemas/authInfo" }, "signatureQualifier": { "type": "string", "description": "Identifier qualifying the type of signature this credential is suitable for (see signatures/signDoc)" } }, "example": { "key": { "status": "enabled", "algo": ["1.2.840.113549.1.1.1", "0.4.0.127.0.7.1.1.4.1.3"], "len": 2048 }, "cert": { "status": "valid", "certificates": [ "", "", "" ], "issuerDN": "", "serialNumber": "5AAC41CD8FA22B953640", "subjectDN": "", "validFrom": "20180101100000Z", "validTo": "20190101095959Z" }, "auth": { "mode": "explicit" }, "lang": "en", "SCAL": "2", "multisign": 5 }, "additionalProperties": true }, "output-credentials-authorize": { "type": "object", "description": "Output parameters for credentials/authorize method", "required": ["SAD"], "properties": { "SAD": { "$ref": "#/components/schemas/SAD" }, "expiresIn": { "$ref": "#/components/schemas/expiresIn" } }, "example": { "SAD": "1/UsHDJ98349h9fgh9348hKKHDkHWVkl/8hsAW5usc8_5=" } }, "output-signatures-signhash": { "type": "object", "description": "Output parameters for signatures/signHash method", "required": ["signatures"], "properties": { "signatures": { "$ref": "#/components/schemas/signatures" } }, "example": { "signatures": [ "KedJuTob5gtvYx9qM3k3gm7kbLBwVbEQRl26S2tmXjqNND7MRGtoew==", "Idhef7xzgtvYx9qM3k3gm7kbLBwVbE98239S2tm8hUh85KKsfdowel==" ] } } } } }