Endpoints

Reference for the eight /v1/sdk/* routes — discovery, session exchange, planning, registration, and evidence ingestion. Request and response shapes for each.

Every Platform API operation is one of eight routes under /v1/sdk/*. This page documents each one: purpose, auth requirements, request body, and response body.

The same authenticated caller — tenant, principal, subject, scopes — resolves under caller in every response. That block is documented once in Authentication → Caller identity on every response and omitted from per-route response tables.

All routes return application/json. Error responses use the envelope documented under Platform API → Error envelope.

Discovery routes

capabilities

GET /v1/sdk/capabilities

Returns the resolved caller identity, active authentication mode, deployment-default scopes, and configured public platform domains. Call this at startup to discover what scopes each route requires.

Auth: BearerAuth or TrustedHeaders.

Response fields:

Field	Type	Notes
`service`	string	Service name.
`status`	string	Typically `ok`.
`auth_mode`	enum	`trusted_headers`, `bearer_token`, or `bearer_token_or_trusted_headers`.
`caller`	object	Resolved caller identity.
`default_required_scopes`	string[]	Deployment default scopes required on every route.
`routes`	array	Per-route capability: `route`, `domain`, `configured`, `required_scopes`.

whoami

GET /v1/sdk/whoami

Returns the resolved caller identity — tenant, principal, subject, scopes. Use it as a lightweight check that credentials are working.

Auth: BearerAuth or TrustedHeaders.

Response fields:

Field	Type	Notes
`service`	string	Service name.
`status`	string	Typically `ok`.
`caller`	object	Resolved caller identity.

bootstrap

GET /v1/sdk/bootstrap

Describes the embedded-enforcement model. Call this once at application startup, cache the result, and use it to select operations and artifact profiles your deployment supports.

Auth: BearerAuth or TrustedHeaders.

Response fields:

Field	Type	Notes
`service`, `status`, `auth_mode`, `caller`	—	See above.
`enforcement_model`	string	The embedded-enforcement mode this deployment operates in.
`plaintext_to_platform`	boolean	Always `false` on supported deployments.
`policy_resolution_mode`	string	How this deployment resolves policy (for example, local or remote-resolve).
`supported_operations`	`ProtectionOperation[]`	Subset of `protect`, `access`, `rewrap`.
`supported_artifact_profiles`	`ArtifactProfile[]`	Subset of `tdf`, `envelope`, `detached_signature`.
`platform_domains`	array	Per-domain status: `domain`, `configured`, `reason`.

Session

session exchange

POST /v1/sdk/session

Exchanges SDK client credentials for a short-lived bearer token. Only needed in deployments configured for SDK client credentials; skip this route if you are using pre-issued bearer tokens. See Authentication → SDK client credentials.

Auth: none; credentials in the request body.

Request fields:

Field	Type	Notes
`tenant_id`	string	Tenant the credentials belong to.
`client_id`	string	SDK client identifier.
`client_secret`	string	SDK client secret.
`requested_scopes`	string[]	Scopes to request for this session.

Response fields:

Field	Type	Notes
`access_token`	string	Short-lived bearer token. Attach as `Authorization: Bearer ...`.
`token_type`	string	Typically `Bearer`.
`expires_in`	integer	Seconds until expiry. SDKs refresh proactively before this.
`scope`	string	Granted scopes.
`tenant_id`, `client_id`, `subject`	string	Resolved identity of the token holder.

Rate limits: 429 responses include Retry-After (seconds).

Protection routes

All protection routes share a common request shape that describes a workload and the resource being acted on. The platform returns a decision (allow / deny, required scopes) and an execution or handling block the caller uses to enforce locally.

Common request components:

Component	Fields
`WorkloadDescriptor`	`application` (required), optional `environment` and `component`.
`ResourceDescriptor`	`kind` (required), optional `id`, `mime_type`.
`labels`	String array of caller-declared tags.
`attributes`	`{ string: string }` map of caller-declared attributes.

protection plan

POST /v1/sdk/protection-plan

Returns a local-enforcement plan for a proposed protect / access / rewrap operation. Metadata only; plaintext is explicitly out of contract.

Auth: BearerAuth or TrustedHeaders.

Request fields:

Field	Type	Notes
`operation`	`ProtectionOperation`	`protect`, `access`, or `rewrap`.
`workload`	`WorkloadDescriptor`	Required.
`resource`	`ResourceDescriptor`	Required.
`preferred_artifact_profile`	`ArtifactProfile`	Optional preference; platform may override in `execution`.
`content_digest`	string	Optional; e.g. `sha256:...`. Absence is signalled on the response.
`content_size_bytes`	integer	Optional.
`purpose`	string	Optional free-text purpose.
`labels`	string[]	Caller tags.
`attributes`	string map	Caller attributes.

Response fields:

Field	Type	Notes
`request_summary`	object	Normalized, sanitized view of the request the platform evaluated.
`decision.allow`	boolean	Whether the operation is authorized.
`decision.required_scopes`	string[]	Scopes that were required to authorize this operation.
`decision.handling_mode`	string	Caller-facing handling mode.
`decision.plaintext_transport`	string	Typically a "local-only" marker.
`execution.protect_locally`	boolean	Whether the SDK should perform the protection operation on the workload.
`execution.local_enforcement_library`	string	The enforcement library the SDK should invoke locally.
`execution.send_plaintext_to_platform`	boolean	Always `false` under the metadata-only stance.
`execution.send_only`	string[]	Metadata fields the SDK is expected to emit to the platform after local work.
`execution.artifact_profile`	`ArtifactProfile`	Profile to use when producing the artifact.
`execution.key_strategy`	string	Caller-facing key-handling strategy descriptor.
`execution.policy_resolution`	string	Caller-facing policy-resolution descriptor.
`platform_domains`	array	Per-domain configured/reason flags.
`warnings`	string[]	Non-fatal advisories.

policy resolve

POST /v1/sdk/policy-resolve

Resolves authorization and handling guidance from metadata only. Useful when the caller wants a policy decision decoupled from a specific artifact profile or key workflow.

Auth: BearerAuth or TrustedHeaders.

Request fields:

Same as protection plan except preferred_artifact_profile is not used.

Response fields:

Field	Type	Notes
`request_summary`	object	Normalized view of the request.
`decision.allow`	boolean	Allow or deny.
`decision.enforcement_mode`	string	Local enforcement mode descriptor.
`decision.required_scopes`	string[]	Scopes required for this decision.
`decision.policy_inputs`	string[]	Caller-facing list of policy inputs considered.
`decision.required_actions`	string[]	Required post-decision actions.
`handling.protect_locally`	boolean	Whether the caller should enforce locally.
`handling.plaintext_transport`	string	Transport marker for plaintext (always local-only).
`handling.bind_policy_to`	string[]	Identifiers the caller should bind the policy decision to.
`handling.evidence_expected`	string[]	Evidence events the caller should emit after enforcement.
`platform_domains`, `warnings`	—	As above.

key access plan

POST /v1/sdk/key-access-plan

Returns guidance for a wrap / unwrap / rewrap flow. The platform authorizes key use; the SDK performs the cryptographic work locally against the key access service.

Auth: BearerAuth or TrustedHeaders.

Request fields:

Field	Type	Notes
`operation`	`KeyAccessOperation`	`wrap`, `unwrap`, or `rewrap`.
`workload`, `resource`	descriptors	Required.
`artifact_profile`	`ArtifactProfile`	Optional.
`key_reference`	string	Optional caller-provided reference to an existing key binding.
`content_digest`	string	Optional.
`purpose`, `labels`, `attributes`	—	Optional.

Response fields:

Field	Type	Notes
`request_summary`	object	Normalized view of the request.
`decision.allow`	boolean	Allow or deny.
`decision.operation`	`KeyAccessOperation`	Echo of the requested operation.
`decision.required_scopes`	string[]	Scopes required.
`decision.key_reference_present`	boolean	Whether the caller supplied a key reference.
`execution.local_cryptographic_operation`	boolean	The SDK performs the cryptographic step locally.
`execution.platform_role`	string	Caller-facing platform role descriptor.
`execution.send_plaintext_to_platform`	boolean	Always `false`.
`execution.send_only`	string[]	Metadata the SDK is expected to emit.
`execution.artifact_profile`	`ArtifactProfile`	Profile to operate against.
`execution.authorization_strategy`	string	Caller-facing authorization-strategy descriptor.
`platform_domains`, `warnings`	—	As above.

Registration

artifact register

POST /v1/sdk/artifact-register

After the SDK has produced a protected artifact locally, this route registers its metadata with the platform. The platform tracks lifecycle without ever seeing the payload.

Auth: BearerAuth or TrustedHeaders.

Request fields:

Field	Type	Notes
`operation`	`ProtectionOperation`	Typically `protect` or `rewrap`.
`workload`, `resource`	descriptors	Required.
`artifact_profile`	`ArtifactProfile`	The profile used to produce the artifact. Required.
`artifact_digest`	string	Cryptographic digest of the protected artifact. Required.
`artifact_locator`	string	Optional pointer to where the artifact is stored.
`decision_id`	string	Optional reference to the earlier decision this registration is bound to.
`key_reference`	string	Optional key binding reference.
`purpose`, `labels`, `attributes`	—	Optional.

Response fields:

Field	Type	Notes
`request_summary`	object	Normalized view of the registration.
`registration.accepted`	boolean	Whether the registration was accepted.
`registration.required_scopes`	string[]	Scopes required.
`registration.artifact_transport`	string	Caller-facing transport descriptor.
`registration.send_plaintext_to_platform`	boolean	Always `false`.
`registration.catalog_actions`	string[]	Downstream catalog actions the platform will perform.
`registration.evidence_expected`	string[]	Evidence events the caller should emit after registration.
`platform_domains`, `warnings`	—	As above.

Evidence ingestion

evidence

POST /v1/sdk/evidence

Records metadata-only evidence events associated with protected artifacts, policy decisions, and local enforcement outcomes. Ingested events land on the Immutable Ledger.

Auth: BearerAuth or TrustedHeaders.

Request fields:

Field	Type	Notes
`event_type`	`EvidenceEventType`	`protect`, `access`, `rewrap`, or `deny`.
`workload`, `resource`	descriptors	Required.
`artifact_profile`	`ArtifactProfile`	Optional.
`artifact_digest`	string	Optional digest of the artifact this event concerns.
`decision_id`	string	Optional reference to the decision this event ties back to.
`outcome`	string	Optional caller-facing outcome descriptor.
`occurred_at`	string	Optional RFC 3339 timestamp.
`purpose`, `labels`, `attributes`	—	Optional.

Response fields:

Field	Type	Notes
`request_summary`	object	Normalized view of the event.
`ingestion.accepted`	boolean	Whether the event was accepted.
`ingestion.required_scopes`	string[]	Scopes required.
`ingestion.plaintext_transport`	string	Always a local-only marker.
`ingestion.send_only`	string[]	Fields the event is expected to carry.
`ingestion.correlate_by`	string[]	Correlation keys the platform will use to link this event to related records.
`platform_domains`, `warnings`	—	As above.

Enumerations

The contract uses four enumeration types:

Enum	Values
`ProtectionOperation`	`protect`, `access`, `rewrap`
`KeyAccessOperation`	`wrap`, `unwrap`, `rewrap`
`ArtifactProfile`	`tdf`, `envelope`, `detached_signature`
`EvidenceEventType`	`protect`, `access`, `rewrap`, `deny`

All enum values are lowercase snake_case. Unknown values are rejected at request validation; the OpenAPI document is authoritative.

Relationship to other pages

SDKs — idiomatic clients for all three supported languages.
Authentication — how callers authenticate before hitting these routes.
Trusted Data Format — the tdf artifact profile is the TDF envelope.
Immutable Ledger — where evidence events land.

On this page