Skip to main content

EmbedSignatureFromDataRequest

mediastring<binary>required

The media file to protect by embedding the SASHA Signature into

callback_secret_idstring

Optional identifier of the Callback Secret SASHA should use to sign the callback payload for this job.

Each Callback Secret you have configured with SASHA has a unique Callback Secret ID. Pass it here to pin a job's callback signature to a specific secret — useful while rotating secrets, or when different parts of your system verify callbacks with different keys.

If omitted, SASHA picks one of your enabled Callback Secrets automatically. The Callback Secret that was actually used is always returned in the SASHA-Callback-Secret-ID HTTP header on the callback request, so your endpoint can look up the matching signing key when validating the SASHA-Request-Signature.

callback_urlstring<uri>

Optional callback URL to receive job status notifications

record object

Optional Record to attach to the resulting signature, carrying the creator's declared distribution intent and display metadata.

Send it as a JSON-encoded string in a record form field with content type application/json, not as nested bracket fields.

Validated at submit: an invalid Record fails the request with a 400 and creates no job. Read-only fields are ignored.

share_stateShareState (string)required

The creator-declared share state of a protected media item:

  • private: The creator declared that the media is not intended to be distributed anywhere public
  • unrestricted: The creator declared no distribution restrictions for the media
  • restricted: The creator declared that the media is intended to be distributed only where the Record's distribution fields permit

A share state describes only the intent the creator has declared to SASHA. It is not a statement about the legal status of the media; rights such as copyright apply independently.

Possible values: [private, unrestricted, restricted]

allowed_publish_urlsstring[]

URL patterns the browser-facing display URL of the media is allowed to match (only meaningful with the restricted share state).

Pattern syntax:

  • https only. The scheme may be omitted; https is implied.
  • A host with no path matches any path on that host: https://cdn.example.com.
  • A path ending in / matches that prefix: https://news.example.com/articles/ matches /articles/123 but not /archive/9. A path not ending in / must match exactly.
  • *. is a subdomain wildcard, and is only allowed as the leftmost label: https://*.example.com. It cannot appear elsewhere, so https://example.com/* is not a valid pattern — omit the path instead. The base of a wildcard must have at least two labels and must not be a public suffix.
  • No userinfo, no query string, no fragment, no IP literals, no localhost.

A pattern that does not parse is rejected with an INVALID_PATTERN field violation naming the entry, e.g. allowed_publish_urls[1].

allowed_source_urlsstring[]

URL patterns the storage/CDN address of the media bytes is allowed to match (only meaningful with the restricted share state).

Same pattern syntax as allowed_publish_urls.

allowed_fromstring<date-time>

The media is not allowed to be available before this time (supports embargo dates)

allowed_tostring<date-time>

The media is not allowed to be available after this time

bylinestring

Display text the publisher is expected to show alongside the media (e.g. photographer credit).

Plain text, no control characters. Consumers must always treat this value as text, never as markup.

Possible values: <= 256 characters

purchase_urlstring<uri>

URL where the media can be purchased or licensed.

Must be a well-formed https URL without userinfo, and must not point at an IP literal or localhost.

Possible values: <= 2048 characters

licenseestring

Legal business name of the entity that has licensed the media asset. Aids enforcers when the licence agreement is not bound to a specific location.

Plain text, no control characters. Consumers must always treat this value as text, never as markup.

Possible values: <= 256 characters

asset_source_idstring

The creator's own upstream source ID for the asset: the creator's identifier for the media in their own system.

Opaque text, no control characters. A UUID (RFC 9562) is recommended but not required. Consumers must always treat this value as text, never as markup.

Possible values: <= 256 characters

custom_fields object

Custom fields, keyed by a creator-chosen name. Custom fields are display/metadata only: they never participate in distribution guidance evaluation, so they may be set under any share state. Disclosure to other parties is governed by the creator's record-access policy (managed by SASHA on the creator's behalf).

property name* FieldValue

A typed value for a custom Record field. Exactly one property is set, which pins the value's type. Custom fields are display/metadata only and never participate in distribution guidance evaluation.

boolean_valueboolean
string_valuestring
int32_valueinteger<int32>
double_valuenumber<double>
uuid_valuestring<byte>

A UUID per RFC 9562 as its 16 raw bytes, base64-encoded.

created_atstring<date-time>

The date and time the Record was first created

updated_atstring<date-time>

The date and time the Record was last replaced

EmbedSignatureFromDataRequest
{
  "media": "string",
  "callback_secret_id": "string",
  "callback_url": "string",
  "record": {
    "share_state": "private",
    "allowed_publish_urls": [
      "string"
    ],
    "allowed_source_urls": [
      "string"
    ],
    "allowed_from": "2024-07-29T15:51:28.071Z",
    "allowed_to": "2024-07-29T15:51:28.071Z",
    "byline": "string",
    "purchase_url": "string",
    "licensee": "string",
    "asset_source_id": "string",
    "custom_fields": {},
    "created_at": "2024-07-29T15:51:28.071Z",
    "updated_at": "2024-07-29T15:51:28.071Z"
  }
}