{
  "openapi": "3.1.0",
  "info": {
    "title": "Signing Server external time stamping API",
    "version": "1.0.0",
    "description": "Obtain validated RFC3161 timestamps with RFC5816 ESSCertIDv2/SHA-256 TSA certificate binding from an administrator-configured external authority. Registered machine requesters authenticate each request with a signed body; human identification is not required. The configured profile fixes the provider, policy, signer and trust. This service returns verified timestamp evidence; the consumer incorporates it into the selected signature format and verifies the completed Baseline level."
  },
  "servers": [
    {
      "url": "https://127.0.0.1:8443",
      "description": "Example HTTPS origin. Configure the actual service origin."
    }
  ],
  "security": [],
  "paths": {
    "/api/timestamp/v1": {
      "post": {
        "operationId": "createExternalTimestamp",
        "summary": "Obtain and verify an external RFC3161 timestamp for a SHA-256 imprint",
        "description": "Explicit timestamp-v1 service mode. Mandatory registered-machine RS256 compact JWS body; no human identity/browser/IdP/consent. Caller selects only an authorized profile and exact imprint. Server chooses external TSA, transport, policy, pinned certificate/chain, validation bounds and fresh nonce. No originals or private issuer keys enter Signing Server. No query, charset or content encoding. Atomic durable REQUESTING consumption precedes one outbound request. Current duplicate requester-scoped IDs return409 forever, including renewed authority; expired incoming authority408 before lookup. Unknown outcomes may mean TSA issuance occurred: reconcile without automatic new ID, retry, poll/reset/resumption or local fallback. Descriptive requester label only; it does not attest format validity. The consumer sends only a SHA-256 digest and retains the covered bytes. For XAdES B-T, signature_value hashes the canonical complete ds:SignatureValue ELEMENT including markup and namespace context, not raw RSA bytes or bare Base64. XAdES archival original-kind hashes the profile-defined concatenation of retained original/reference octets and canonical XML components. PAdES signature_value retains its raw RSA signature-value coverage. For JAdES B-T, signature_value hashes ASCII of the exact canonical unpadded base64url signature member, not raw RSA or quoted JSON. JAdES archival original-kind hashes original exact octets, ASCII period+protected+period+signature+period, then exact preceding encoded etsiU strings without separators, quotes or the new archive component. Other uses retain their integration-defined exact input. The consumer owns complete signature-profile validation.",
        "security": [],
        "x-authentication": {
          "location": "requestBody",
          "format": "JWS compact serialization",
          "protectedHeaderSchema": "timestamp.header.schema.json",
          "decodedPayloadSchema": "timestamp.request.schema.json",
          "keySource": "administrator-pinned RSA SPKI by kid",
          "algorithm": "RS256",
          "maxDecodedHeaderBytes": 2048,
          "maxDecodedPayloadBytes": 8192
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/jose": {
              "schema": {
                "type": "string",
                "maxLength": 16384,
                "pattern": "^[A-Za-z0-9_-]+[.][A-Za-z0-9_-]+[.][A-Za-z0-9_-]+$"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verified public timestamp token, returned only after durable completion. Independently verify signature/chain/policy/nonce/imprint against the exact integration/profile-defined retained covered bytes. imprint_kind is descriptive and does not establish complete signature-profile validity.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                }
              }
            }
          },
          "400": {
            "description": "invalid_request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "not_authorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "408": {
            "description": "expired_request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "duplicate_request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "request_too_large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "unsupported_media_type",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "capacity_exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "unavailable or outcome_unknown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Exact path only; no query.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "POST only.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "invalid_timestamp or provider_rejected; no unvalidated or partial token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Result": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "version",
          "request_id",
          "transaction_id",
          "profile",
          "provider",
          "imprint_kind",
          "algorithm",
          "imprint",
          "policy",
          "nonce",
          "generated_at",
          "verified_at",
          "accuracy_micros",
          "certificate_sha256",
          "certificates",
          "token"
        ],
        "properties": {
          "version": {
            "const": 1
          },
          "request_id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{19,95}$"
          },
          "transaction_id": {
            "type": "string",
            "pattern": "^timestamp-[0-9a-f]{64}$"
          },
          "profile": {
            "type": "string",
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
          },
          "provider": {
            "type": "string",
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
          },
          "imprint_kind": {
            "enum": [
              "original",
              "signature_value"
            ],
            "description": "Descriptive requester label only; it does not attest format validity. The consumer sends only a SHA-256 digest and retains the covered bytes. For XAdES B-T, signature_value hashes the canonical complete ds:SignatureValue ELEMENT including markup and namespace context, not raw RSA bytes or bare Base64. XAdES archival original-kind hashes the profile-defined concatenation of retained original/reference octets and canonical XML components. PAdES signature_value retains its raw RSA signature-value coverage. For JAdES B-T, signature_value hashes ASCII of the exact canonical unpadded base64url signature member, not raw RSA or quoted JSON. JAdES archival original-kind hashes original exact octets, ASCII period+protected+period+signature+period, then exact preceding encoded etsiU strings without separators, quotes or the new archive component. Other uses retain their integration-defined exact input. The consumer owns complete signature-profile validation."
          },
          "algorithm": {
            "const": "SHA256"
          },
          "imprint": {
            "type": "string",
            "contentEncoding": "base64",
            "minLength": 44,
            "maxLength": 44,
            "pattern": "^[A-Za-z0-9+/]{43}=$",
            "description": "Canonical standard base64 of exactly 32 SHA-256 digest bytes. Original files, raw signatures and profile-defined canonical/archival covered bytes remain with the consumer; only the digest is sent. The descriptive imprint_kind does not establish format coverage or validity."
          },
          "policy": {
            "type": "string",
            "maxLength": 128,
            "pattern": "^[0-2]([.][0-9]+)+$"
          },
          "nonce": {
            "type": "string",
            "pattern": "^[89a-f][0-9a-f]{39}$"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Validated TSA genTime; UTC Z and nanosecond precision preserved."
          },
          "verified_at": {
            "type": "string",
            "format": "date-time"
          },
          "accuracy_micros": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 60000000,
            "description": "Declared accuracy only; absent is unknown, never zero by assumption."
          },
          "certificate_sha256": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "certificates": {
            "type": "array",
            "minItems": 2,
            "maxItems": 4,
            "items": {
              "type": "string",
              "contentEncoding": "base64",
              "maxLength": 21848
            }
          },
          "token": {
            "type": "string",
            "contentEncoding": "base64",
            "minLength": 4,
            "maxLength": 87384,
            "description": "Canonical DER CMS ContentInfo carrying id-ct-TSTInfo; not the outer TimeStampResp."
          }
        }
      },
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "invalid_request",
              "unauthenticated",
              "not_authorized",
              "expired_request",
              "duplicate_request",
              "request_too_large",
              "unsupported_media_type",
              "capacity_exceeded",
              "invalid_timestamp",
              "provider_rejected",
              "unavailable",
              "outcome_unknown",
              "not_found",
              "method_not_allowed"
            ]
          }
        }
      }
    }
  },
  "externalDocs": {
    "url": "https://github.com/fortifiedid/signing-server/blob/main/docs/70-integration/TIMESTAMP.md",
    "description": "Registration, configuration, errors, reconciliation and consumer verification"
  },
  "x-event-log-configuration": {
    "schema": "event-log.configuration.schema.json",
    "contract": "event-log.contract.json",
    "scope": "Optional trusted local event_log section for this explicit service mode; not an HTTP request field. Absent means disabled; database audit and signing authorization remain separate."
  }
}
