Skip to main content
Enterprise organizations can keep authentication photos and certificates off the public CDN. Uploads go to a private bucket. Reads return CloudFront-signed URLs. The public share page does not show photos. Create, read, and submit service requests stay the same partner APIs. Only the upload path and the shape of media URLs change. If your organization is on the public CDN, use the standard Workflow upload path (GET /intent) instead.

Required scope

Your API key must include media:v2:private-read in addition to sr:v2:create and sr:v2:read. Legitmark grants this scope when private media is enabled for your organization. Send the same leo_ key on every call below:
Without media:v2:private-read, GET /api/v2/sr/{sr_uuid} returns empty media_url arrays and a null certificate_url for private-CDN organizations.

Integration steps

Same flow as the public partner API, with two changes: do not call /intent, and treat every media URL as short-lived.
1

Create the service request

POST /api/v2/sr?sides=true&item=true with your leo_ key and the usual body. Passing sides=true&item=true returns the required/optional photo list inline so you do not need a second fetch before upload.API Reference: POST /api/v2/sr
2

Upload photos

POST /api/media/signed-urls/{sr_uuid} once for all sides, then PUT each image to the returned signed_url. Do not call GET /intent.
3

Read photos

GET /api/v2/sr/{sr_uuid}?item=true&sides=true with the same key. media_url (and summary.thumbnail if you pass summary=true) are signed private-CDN links that last about 15 minutes.
4

Read the certificate

Use certificate_url from the latest Get Full SR. If you get Access Denied or 403, fetch again. You can also regenerate from Download certificate in the dashboard.

Upload photos

Do not call GET https://asset.legitmark.com/intent (or the development/staging asset host). That route writes to the public bucket and cannot route private-organization uploads. Request every side’s upload URL in one call, then PUT the image bytes to each URL. API Reference: POST /api/media/signed-urls/{sr_uuid}
Request body Response
Do not send your Authorization header on the PUT to signed_url. The URL is already signed, and S3 rejects the request with 400 if an Authorization header is present. Only the POST /api/media/signed-urls/{sr_uuid} call uses your API key.
The TypeScript SDK still uses GET /intent. Private-CDN organizations should call POST /api/media/signed-urls/{sr_uuid} over HTTP until the SDK is updated.

Browser uploads (CORS)

If a warehouse or web app PUTs the image from the browser, S3 must allow that page’s origin. Share every upload origin with Legitmark (exact origins and https://*.example.com wildcards). Origins already allowlisted for your organization keep working. A CORS error on the PUT means a new origin needs to be added — do not fall back to /intent.

Read photos

Fetch the service request with the same API key. media_url values are CloudFront-signed links on your private CDN host. API Reference: GET /api/v2/sr/{sr_uuid}
A signed read URL looks like this (query values are truncated):
  • Keep Expires, Key-Pair-Id, and Signature on the URL. Stripping the query string returns 403.
  • summary.thumbnail is signed the same way when you pass summary=true.
  • Public cdn.legitmark.com links from earlier testing no longer serve these photos.

Certificates

certificate_url on the latest GET /api/v2/sr/{sr_uuid} is a signed PDF link on the same private host. Use that URL. If you get Access Denied or 403, the signature expired — call GET again and use the new URL. You can also regenerate a fresh link from Download certificate in the dashboard (https://app.legitmark.com or the development/staging app host). Do not reuse a certificate link you stored earlier.

URL lifetime

Signed read URLs last 15 minutes from the moment they are issued (expires_in default 900 seconds).
  • Do not persist or cache signed URLs in your database.
  • Do not log or forward a signed URL as a durable share link. Anyone who has the URL can fetch the object until it expires.
  • Call GET /api/v2/sr/{sr_uuid} again whenever you need to display or download a photo or certificate.
  • An expired or unsigned URL returns 403. That is expected. Fetch a fresh URL.
Webhook payloads do not include media URLs. When a state_change arrives, fetch the SR if you need photos or the certificate.

Public share page

The public share page does not show photos for private-CDN organizations. That is intended. Photos and certificates stay available through the partner API with your keyed requests.

Environments

Replace {org} with the hostname Legitmark provisioned for your organization. Use the URL returned by the API rather than constructing CDN hosts yourself.

Image requirements

Same as the public workflow:
  • Format: JPG/JPEG/PNG
  • Size: 600 x 600 px minimum
  • File size: 5 MB maximum per image
  • Quality: Clear, well-lit, focused images