Skip to main content

EmbedSignatureFromURLRequest

media_urlstringrequired

The URL of the media file to protect by embedding the SASHA Signature into

Example: https://example.com/image.jpg
media_mime_typestring

The MIME type of the media file at the given URL.

If not provided, the MIME type will be inferred from the URL.

The following MIME types are currently supported:

  • image/jpeg
  • image/png
  • image/webp
  • video/mp4, video/quicktime and application/mxf (video; accepted for URL submissions only)

The protected video keeps the input's container, MP4, MOV or MXF, e.g. MXF for an XDCAM MXF input, and MOV with DNxHR video for a ProRes MOV input; see the Supported Formats reference below for the format table.

For the most up-to-date list of supported formats and other media constraints, see the Supported Formats reference.

Example: image/jpeg
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.

Example: 177F01DA-34F2-4318-9763-B73876FDD7FA
callback_urlstring<uri>

Optional callback URL to receive job status notifications

Example: https://your-app.com/callbacks/sasha-job-update
record object

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

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

share_stateShareStaterequired

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].

Example: ["https://news.example.com/articles/"]
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.

Example: ["https://cdn.example.com"]
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

Example: Photo by Jane Doe
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

Example: https://license.example.com/photos/123
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

Example: Example Media Group Ltd.
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

Example: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
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. Each custom field is disclosed to other parties like any other Record field: to the creators the owner has granted it to, or to every looker once the owner marks it public. SASHA manages these settings 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

EmbedSignatureFromURLRequest
{
  "media_url": "https://example.com/image.jpg",
  "media_mime_type": "image/jpeg",
  "callback_secret_id": "177F01DA-34F2-4318-9763-B73876FDD7FA",
  "callback_url": "https://your-app.com/callbacks/sasha-job-update",
  "record": {
    "share_state": "private",
    "allowed_publish_urls": [
      "https://news.example.com/articles/"
    ],
    "allowed_source_urls": [
      "https://cdn.example.com"
    ],
    "allowed_from": "2024-07-29T15:51:28.071Z",
    "allowed_to": "2024-07-29T15:51:28.071Z",
    "byline": "Photo by Jane Doe",
    "purchase_url": "https://license.example.com/photos/123",
    "licensee": "Example Media Group Ltd.",
    "asset_source_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "custom_fields": {},
    "created_at": "2024-07-29T15:51:28.071Z",
    "updated_at": "2024-07-29T15:51:28.071Z"
  }
}