--- updatedAt: 2026-05-17T10:49:23.000Z agentTools: siteIndex: https://docs.jfrog.com/llms.txt projectIndex: https://docs.jfrog.com/governance/llms.txt --- # Prepare Evidence for Signing Prepares an in-toto statement for external signing. Returns the DSSE payload (base64-encoded) and the URL to POST the signed envelope to. This is the first step in a two-step evidence creation flow: 1. Call this endpoint to prepare the statement and receive the DSSE payload 2. Sign the payload externally and POST the signed DSSE envelope to the returned `post_url` # OpenAPI definition ````json { "openapi": "3.1.0", "info": { "title": "JFrog Artifactory Evidence API", "description": "REST API for managing evidence records in JFrog Artifactory. Evidence records are secure, verifiable attestations about your software artifacts. They are crucial for establishing a chain of custody and ensuring compliance throughout your software supply chain.", "version": "1.0.0", "contact": { "name": "JFrog Support" } }, "servers": [ { "url": "https://{jfrog_url}/evidence/api/v1", "description": "Evidence API base path" } ], "tags": [ { "name": "Evidence", "description": "Evidence management operations" } ], "paths": { "/evidence/prepare": { "post": { "tags": [ "Evidence" ], "summary": "Prepare Evidence for Signing", "description": "Prepares an in-toto statement for external signing. Returns the DSSE payload (base64-encoded) and the URL to POST the signed envelope to.\n\nThis is the first step in a two-step evidence creation flow:\n1. Call this endpoint to prepare the statement and receive the DSSE payload\n2. Sign the payload externally and POST the signed DSSE envelope to the returned `post_url`\n", "operationId": "prepareEvidence", "parameters": [ { "name": "include_pae", "in": "query", "description": "When set to true, includes the Pre-Authentication Encoding (PAE) string in the response", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "description": "In-toto statement generation request containing the predicate, predicate type, and subject information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareEvidenceRequest" } } } }, "responses": { "200": { "description": "OK - Statement prepared successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepareEvidenceResponse" } } } }, "400": { "description": "Bad Request - Invalid request body or subject information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Bad Credentials - The request failed because the authentication token is invalid or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found - The specified subject could not be resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "412": { "description": "Precondition Failed - Requested attachment features are not supported by the connected Artifactory version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload Too Large - The request body exceeds the maximum allowed size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "ErrorResponse": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/Error" } } } }, "Error": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "details": { "type": "array", "items": { "type": "string" }, "description": "Optional additional error details" } } }, "AttachmentInput": { "type": "object", "description": "Reference to an attachment file stored in Artifactory", "required": [ "repository", "path" ], "properties": { "repository": { "type": "string", "description": "Artifactory repository key where the attachment source file resides", "example": "my-generic-repo" }, "path": { "type": "string", "description": "Path to the attachment file within the repository", "example": "reports/build-log.txt" }, "sha256": { "type": "string", "description": "SHA-256 checksum of the attachment file. Optional in prepare requests because the service resolves it. Required when submitting the final signed create request so the attachment set can be validated against the signed statement.\n", "example": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } } }, "PrepareEvidenceRequest": { "type": "object", "description": "Request to prepare an in-toto statement for external signing", "required": [ "predicate", "predicate_type", "subject" ], "properties": { "predicate": { "type": "object", "description": "The in-toto predicate JSON object containing the attestation claims", "example": { "builder": { "id": "https://github.com/actions/runner" }, "buildType": "https://github.com/actions/workflow@v1" } }, "predicate_type": { "type": "string", "description": "Predicate type URI (e.g., https://slsa.dev/provenance/v0.2)", "example": "https://slsa.dev/provenance/v0.2" }, "markdown": { "type": "string", "description": "Optional markdown representation of the evidence", "example": "### Build Success\nThe binary was compiled using Go 1.22." }, "provider_id": { "type": "string", "description": "Evidence provider identifier", "example": "github-actions" }, "subject": { "$ref": "#/components/schemas/SubjectInput" }, "attachments": { "type": "array", "maxItems": 1, "items": { "$ref": "#/components/schemas/AttachmentInput" }, "description": "Source references to attachment files in Artifactory. The service resolves `sha256` values during prepare. At most one attachment is supported. Requires Artifactory >= 7.142.0.\n" }, "project_key": { "type": "string", "description": "JFrog project key. Selects the project-qualified system repository when `subject.subject_type` is `build`, `release_bundle`, or `application_version` (omit or `default` → default project). Also used for entity scope when `subject.subject_type=entity` (maps to the `project` query parameter on `POST /entity/{type}/{id}`): **non-artifact entities** derive `{project}-{type}-entity`; reserved **`build-version` / `release-bundle-version` / `application-version`** select the project-qualified system repo. For entity scope, mutually exclusive with `application_key` and `entity_repo`.\n", "example": "default" }, "application_key": { "type": "string", "description": "Application key for entity scope when `subject.subject_type=entity`. Maps to the `application` query parameter on `POST /entity/{type}/{id}`. **Non-artifact entities only.** Distinct from `SubjectInput.application_key`. Mutually exclusive with `project_key` and `entity_repo`.\n", "example": "my-app" }, "entity_repo": { "type": "string", "description": "Artifactory repository key for entity scope when `subject.subject_type=entity`. Maps to the `repo` query parameter on `POST /entity/{type}/{id}`. **Non-artifact entities:** explicit entity repository override. **Reserved `artifact` / `package-version`:** required. Mutually exclusive with `project_key` and `application_key`.\n", "example": "my-entity-repo" } } }, "SubjectInput": { "type": "object", "description": "Subject information identifying the artifact, build, package, release bundle, application version, or entity", "required": [ "subject_type" ], "properties": { "subject_type": { "type": "string", "enum": [ "artifact", "build", "package", "release_bundle", "application_version", "entity" ], "description": "Type of subject", "example": "artifact" }, "subject_sha256": { "type": "string", "description": "SHA-256 checksum of the subject", "example": "4529c29807530e38676d08ca61a6c4b2208034440c83d65a881f211364d95267" }, "entity_type": { "type": "string", "description": "Entity type (required when `subject_type=entity`). Non-artifact examples: `gitCommit`. Reserved types: `artifact`, `package-version`, `application-version`, `release-bundle-version`, `build-version`.\n", "example": "gitCommit" }, "entity_id": { "type": "string", "description": "Entity identifier when `subject_type=entity`. Same formats as the `id` path\nparameter on `POST /entity/{type}/{id}`:\n\n**Non-artifact:** typically a single segment (`[-_.A-Za-z0-9]`).\n\n**Reserved artifact-backed:**\n- `artifact` — repo-relative `{path}/{name}` (may contain `/`); repo via `entity_repo`\n- `package-version` — `{name}/versions/{version}` (split on last `/versions/`);\n name shape is package-type-specific (Maven `g:a`, npm `@scope/pkg`, Docker\n image path, Go module path, etc.); package type from `entity_repo` config\n- `application-version` — `{applicationKey}/{version}` (exactly two segments)\n- `release-bundle-version` — `{bundleName}/{version}` (exactly two segments)\n- `build-version` — `{buildName}/{buildNumber}` or\n `{buildName}/{buildNumber}/{timestamp}` (timestamp: digits only, ≤ 64)\n", "example": "57bb812f3733b80e270272ba063274e52c34bd23" }, "repo_path": { "type": "string", "description": "Repository path (required when subject_type=artifact)", "example": "my-repo/path/to/artifact.jar" }, "build_name": { "type": "string", "description": "Build name (required when subject_type=build)", "example": "my-build" }, "build_number": { "type": "string", "description": "Build number (required when subject_type=build)", "example": "123" }, "build_timestamp": { "type": "string", "description": "Build timestamp, numeric only (optional when subject_type=build)", "example": "1709000000" }, "release_bundle_name": { "type": "string", "description": "Release bundle name (required when subject_type=release_bundle)", "example": "my-bundle" }, "release_bundle_version": { "type": "string", "description": "Release bundle version (required when subject_type=release_bundle)", "example": "1.0.0" }, "application_key": { "type": "string", "description": "Application key (required when subject_type=application_version)", "example": "my-app" }, "application_version": { "type": "string", "description": "Application version (required when subject_type=application_version)", "example": "1.0.0" }, "package_repo": { "type": "string", "description": "Package repository (required when subject_type=package)", "example": "npm-local" }, "package_name": { "type": "string", "description": "Package name (required when subject_type=package)", "example": "my-package" }, "package_version": { "type": "string", "description": "Package version (required when subject_type=package)", "example": "1.0.0" } } }, "PrepareEvidenceResponse": { "type": "object", "description": "Response containing the prepared DSSE payload for external signing", "properties": { "post_url": { "type": "string", "description": "URL to POST the signed DSSE envelope to after signing. For entity subjects: `/evidence/api/v1/entity/{type}/{id}` with optional `repo`, `project`, or `application` query. Non-artifact entities use a typed digest; reserved artifact-backed entity types use `sha256` of the lead file.\n", "example": "/evidence/api/v1/entity/gitCommit/57bb812f3733b80e270272ba063274e52c34bd23?project=default" }, "dsse_payload": { "type": "string", "format": "byte", "description": "Base64-encoded serialized in-toto Statement to be signed. Decoded shape for\nan artifact or artifact-backed entity subject:\n\n```json\n{\n \"_type\": \"https://in-toto.io/Statement/v1\",\n \"subject\": [\n {\n \"name\": \"example-binary\",\n \"digest\": { \"sha256\": \"4529c29...\" }\n }\n ],\n \"predicateType\": \"https://slsa.dev/provenance/v0.2\",\n \"predicate\": { \"...\": \"...\" },\n \"createdAt\": \"2026-02-09T11:45:00Z\",\n \"createdBy\": \"github-actions-bot\"\n}\n```\n\nFor non-artifact entity subjects the digest key is the entity type (e.g. `gitCommit`)\ninstead of `sha256`:\n\n```json\n{\n \"_type\": \"https://in-toto.io/Statement/v1\",\n \"subject\": [\n {\n \"name\": \"57bb812f3733b80e270272ba063274e52c34bd23\",\n \"digest\": { \"gitCommit\": \"57bb812f3733b80e270272ba063274e52c34bd23\" }\n }\n ],\n \"predicateType\": \"https://slsa.dev/provenance/v0.2\",\n \"predicate\": { \"...\": \"...\" },\n \"createdAt\": \"2026-02-09T11:45:00Z\",\n \"createdBy\": \"github-actions-bot\"\n}\n```\n", "example": "eyJfdHlwZSI6Imh0dHBzOi8vaW4tdG90by5pby9TdGF0ZW1lbnQvdjEiLCJzdWJqZWN0IjpbeyJuYW1lIjoiZXhhbXBsZS1iaW5hcnkiLCJkaWdlc3QiOnsic2hhMjU2IjoiNDUyOWMyOTgwNzUzMGUzODY3NmQwOGNhNjFhNmM0YjIyMDgwMzQ0NDBjODNkNjVhODgxZjIxMTM2NGQ5NTI2NyJ9fV0sInByZWRpY2F0ZVR5cGUiOiJodHRwczovL3Nsc2EuZGV2L3Byb3ZlbmFuY2UvdjAuMiIsInByZWRpY2F0ZSI6e30sImNyZWF0ZWRBdCI6IjIwMjYtMDItMDlUMTE6NDU6MDBaIiwiY3JlYXRlZEJ5IjoiZ2l0aHViLWFjdGlvbnMtYm90In0=" }, "dsse_payload_type": { "type": "string", "description": "DSSE payload type (application/vnd.in-toto+json)", "example": "application/vnd.in-toto+json" }, "pre_authentication_encoding": { "type": "string", "description": "Pre-Authentication Encoding (PAE) string (returned when include_pae=true)", "example": "DSSEv1 28 application/vnd.in-toto+json 312 {\"_type\":\"https://in-toto.io/Statement/v1\",...}" }, "attachments": { "type": "array", "maxItems": 1, "items": { "$ref": "#/components/schemas/AttachmentInput" }, "description": "Resolved attachment references with `sha256` checksums. Pass these back with the signed envelope to `POST /subject/{subjectRepoPath}`. At most one attachment is returned. Requires Artifactory >= 7.142.0.\n" } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT token authentication" } } }, "security": [ { "bearerAuth": [] } ] } ````