Skip to main content
Version: 1.4.0

SASHA Partner API

This API allows protecting new images and checking if an image is already protected with SASHA Signature.

Authenticate with Client Credentials​

To authenticate with Client Credentials, you need to send a request to the /oauth/token endpoint.

The server will authenticate the Partner and return an Access Token that can be used for making requests to the Signature endpoints.

Protect an image with SASHA Signature​

To protect an image with SASHA Signature, you need to send a request to the /signature/embed endpoint, providing the image file or the URL to the image file.

The server will return a Job object with the job ID and status. Once the job is complete, the protected image file will be available at the output_url and the signature_id will be populated representing the globally unique identifier of the protected image.

Partners may poll for the job status using the /jobs/{job_id} endpoint or provide a callback_url in the request to receive notifications when the job is complete.

Check if an image is already protected with SASHA Signature​

To check if an image is already protected with SASHA Signature, you need to send a request to the /signature/lookup endpoint, providing the image file or the URL to the image file.

The server will return a Job object with the job ID and status. Once the job is complete, the Job object will contain the signature_id and creator_id fields if a SASHA Signature is found.

Records and Distribution Guidance​

Partners can attach a Record to a signature they registered using the /signature/{signature_id}/record endpoints. A Record carries the creator's declared distribution intent (where and when the media is allowed to appear) and display metadata.

When a lookup finds a signature, the completed Job includes a guidance object: SASHA's evaluation of the found signature's Record against the publish_url and source_url provided in the lookup request. Guidance contains coarse values plus an optional human-readable message; the Record contents are never disclosed to the party performing the lookup, though the message may name domains from the Record's allowed URL patterns (domain names are public knowledge).

Job Status and Callbacks​

All operations are asynchronous and return a Job object with a unique job_id. You can:

  1. Poll for status: Use the /jobs/{job_id} endpoint to check job status.
  2. Callback notifications: Provide a callback_url in your request to receive notifications when the job status changes.

Callback Notifications​

If you provide a callback_url in your Embed Signature or Lookup Signature request, the system will send HTTP POST requests to that URL whenever the job status changes. The callback payload will contain the complete Job object with updated status information. Partners can use this callback to track the status of their jobs and get notified when the job is complete to get the result.

Partners can validate the callback request to ensure it genuinely comes from SASHA and was not modified in transit, see callback documentation below.

Error responses​

Every response carries a SASHA-Request-ID header identifying that request. Quote it when contacting SASHA support: it is what joins your call to the server-side logs.

A failing request to the Signature, Job or Record endpoints returns an ErrorResponse:

{
  "message": "purchase_url must use the https: protocol (+2 more)",
  "request_id": "8f14e45f-ceea-467a-9f0b-2b3a2c5a7d61",
  "details": [
    {
      "field": "purchase_url",
      "reason": "UNSUPPORTED_SCHEME",
      "description": "purchase_url must use the https: protocol"
    }
  ]
}
  • message is always present. On a validation failure it is the first details entry's description, suffixed with (+N more) when the request has more than one violation.
  • request_id mirrors the SASHA-Request-ID response header.
  • details is present on validation failures only, and lists at most 20 violations. Each entry names the offending field in request-body naming (purchase_url, allowed_publish_urls[2], custom_fields["asset_id"].string_value), a machine-readable reason, and a human-readable description that never echoes the value you submitted.

Branch on reason, never on the text of message or description. The reason catalogue is REQUIRED, INVALID_TYPE, INVALID_FORMAT, UNSUPPORTED_SCHEME, FORBIDDEN_USERINFO, FORBIDDEN_HOST, TOO_LONG, TOO_MANY, INVALID_CHARACTERS, UNKNOWN_VALUE, NOT_ALLOWED_HERE, EXACTLY_ONE_REQUIRED, UNKNOWN_FIELD, EMPTY and INVALID_PATTERN; each value is documented on the FieldViolation schema. The set is closed, but it may be extended with new reasons — treat a reason you do not recognise as a generic validation failure rather than failing hard.

The /oauth/token endpoint is the exception: it returns the OAuth 2.0 error shape (error, error_description, error_uri) defined by RFC 6749.

Authentication​

Base64-encoded string that contains the Client ID and Client Secret.

The Client ID and Client Secret must each be form-url-encoded.

The field must have the format: Authorization: Basic <base64-encoded client_id:client_secret>

Security Scheme Type:

http

HTTP Authorization Scheme:

basic

Contact

API Support: support@sasha.eu