Frontify API

Authentication

Which mode to use S8

Authorization-code flow S8

1. Redirect the user to GEThttps://{tenant-domain}/api/oauth/authorize?response_type=code&client_id=…&redirect_uri=…&scope=basic:read%20basic:write&state=…[&code_challenge=…&code_challenge_method=S256]. At least basic:read is required; scopes must be enabled on the client. The user sees a consent screen listing the scopes.
2. Frontify redirects back with the authorization code and state (verify state against CSRF). Unverified The page names the parameter authorization_code in its example redirect URL but code elsewhere — check both.
3. POSThttps://{tenant-domain}/api/oauth/accesstoken (JSON or multipart) with grant_type=authorization_code, code, client_id, redirect_uri, scope (+-separated), plus client_secret (confidential) or code_verifier (PKCE) → {token_type: "Bearer", expires_in, access_token, refresh_token}.
4. Refresh: POST/api/oauth/refresh with grant_type=refresh_token, refresh_token, client_id, scope (+ client_secret if confidential).
5. Revoke: POST/api/oauth/revoke with token and optional token_type_hint → HTTP 200.

Multi-tenancy: clients must know the customer's domain; the Authenticator lets the app fix it or lets the user type it, and returns it in bearerToken.domain S45 S46. OpenID discovery (/.well-known/openid-configuration) is not served on instances S65.

Core resources

All operations are fields on RootQuery / RootMutation of POST/graphql. "β" = flagged beta in the legacy reference (needs X-Frontify-Beta: enabled) S63. Domain grouping follows the official reference S62.

Data model

• Hierarchy: everything belongs to an Account; an account holds Users and Brands; a brand holds Libraries (finalised, widely consumable assets), Workspace projects (called Projects in the UI: work-in-progress, collaboration) and Guidelines (pages) S3. Library types: MEDIA_LIBRARY, ICON_LIBRARY, LOGO_LIBRARY, DOCUMENT_LIBRARY S62; icon libraries accept SVG only S19.
• Identifiers: global IDs are Base64-encoded JSON {"identifier": <int>, "type": "<type>"} (so they start with ey…); some queries still accept the numeric ID from UI URLs, but that is slated for deprecation S30. externalId (≤ 255 characters) stores a foreign key on assets; it is not unique S19 S22.
• Asset vs file: a File is an uploaded binary that can back an Asset, an Attachment, a revision or a font; asset creation is separate from upload S3 S19.
• Asset types (interface Asset): Image, Video, Audio, Document, File (fallback when unclassified or processing failed), EmbeddedContent (external URL assets) S4 S62. Classification by extension after asynchronous processing (e.g. Image: bmp, dng, eps, gif, jpg, png, psd/psb, svg, tif, webp, heif…; Video: avi, mkv, mov, mp4, webm…; Document: docx, pptx, xlsx…) S4; .ai files became Documents on 2026-05-06 S34.
• Common asset fields: title, description, alternativeText, isDecorative (images), author, tags (source: MANUAL or AUTO for AI tags), copyright, licenses, availability {from,to}, expiresAt, status (PROCESSING, FINISHED, PROCESSING_FAILED), customMetadata, workflowTask, location (folder breadcrumb), relatedAssets, revisions, variants, attachments, comments, targets, createdAt/modifiedAt, fileCreatedAt S62 S34. Images add width, height, focalPoint, previewBackgroundColor, and a beta provenance object (content-credential state, content origin, generator, signing certificate) S62.
• Custom metadata: property types TEXT, LONGTEXT, NUMBER, DATE (YYYY-MM-DD), URL, SELECT, MULTISELECT, CATALOG S62 S25; options have Base64 IDs; properties can be required (assets missing a required value stay hidden from end users), searchable/viewable, conditionally dependent (FILLED, SELECT_EQUALS, SELECT_ONE_OF) and permissioned (VIEW/EDIT/ADMIN per role, user or group) — the advanced settings are beta S25 S34.
• Revisions: asset.revisions (id, dates, creator) since 2026-06; no file/URL info per revision yet S34.

Search & querying

• Max page size 100; deep pagination via page (no documented offset ceiling outside searches) S16 S20.
• Facets/aggregations are not exposed by the API (facets are a UI configuration) Unverified (no aggregation field found in the schema S62).

Uploads & binaries

Upload flow (3 steps) S19 S62

1. uploadFile(input: {filename, size}) → {id, urls[]}: a temporary file ID and presigned S3 part URLs. Part count is computed from the size: max 1,000 parts, files < 15 MB in one part, otherwise 15 MB–5 GB parts; maximum file size 5 TB (the guide itself says "no limit") Unverified. Supplying chunkSize manually is deprecated since 2026-01-01 S34.
2. PUT each chunk (ceil(size / number_of_urls) bytes) as the raw body to its URL — no Frontify token on these calls S19.
3. Use the file ID once: createAsset(input: {fileId, parentId, title, description, alternativeText, externalId, tags, copyright, availability, expiresAt, author, skipFileMetadata, previewBackgroundColor}) → job { assetId }; parentId is the Base64 ID of a library, workspace project or folder. The same file ID can instead feed replaceAsset (new revision), createAttachment or variant mutations S19 S22 S62. skipFileMetadata: true ignores embedded EXIF/XMP S34.

• Executables (exe, dmg, sh, bat, cmd…) are rejected S19. After creation the asset exists immediately but is PROCESSING; previews and type classification follow asynchronously, normally seconds to a minute, up to 15 minutes worst case S4.
• Bulk migrations: Frontify's own guide recommends upload + create + custom metadata per file, keyed by externalId, with account:read basic:read basic:write; libraries must be pre-created in the UI S21.

Downloads & renditions S24 S57

• previewUrl(width, height): CDN URL for a specific revision; never expires, stays valid even if the asset is later changed or deleted; accepts Media Processing parameters S57 S62.
• thumbnailUrl: custom thumbnail, falling back to the preview S24.
• dynamicPreviewUrl (beta, needs X-Frontify-Beta: enabled and X-Frontify-Development-Flags: PUBLIC_API_DYNAMIC_CDN): stable URL always serving the latest revision; 1-year CDN TTL with near-real-time invalidation; stops working when the asset is deleted S24 S57. Not present in the published SDL S62.
• downloadUrl(validityInDays, permanent): original file; null when download-protected for the user (check currentUserPermissions.canDownload); permanent: true → non-expiring URL always pointing to the latest version; otherwise a version-pinned expiring URL S24 S10. Unverified Default validity is stated as 7 days S24, 1 day (January 2023 changelog) and 6 days with a 1–6 day range (2022 changelog) S34 — pass validityInDays explicitly.
• Media Processing API: append ?mod=v1/<op>/<op>… to a preview or dynamic URL; chained operations include resize, cover, contain, inside, crop (with coordinates), focus (incl. focus=auto), refit-cover/refit-inside (subject-aware), background (incl. background=remove), colorize, flip, quality/quality-min/quality-max, output=maincolor|meancolor|preview|blank, download=, colour-vision simulations; output capped at 4096 px, metadata stripped, original not retrievable through the CDN; WebP/next-gen formats chosen by content negotiation; PDFs rendered as first-page image inside <img> or served whole when linked S56 S57 S59. Delivered through AWS CloudFront, decoupled from the application (keeps serving if the app is down) S58.

Events & webhooks

Configuration S35 S36 S11

• Managed only through GraphQL: configureProjectWebhook(input: {projectId, notificationUrl, name, version: 2, subscribeTo?: [AssetWebhookEvent]}) (v2; omit subscribeTo for all events), installProjectWebhook (v1), webhooks(limit, page) to list, uninstallWebhook(input: {id}) (returns only the ID since 2026-09-18).
• Scope: one library or workspace project (projectId). Requires webhook:write + basic:write and Editor rights on that location; reading requires webhook:read.
• The subscribed event list cannot be queried back after creation — store it yourself S36.
• Response to install includes the webhook secret S36.

Events (v2, enum AssetWebhookEvent) S41 S62: ASSET_CREATED, ASSET_UPDATED (generic: title, description, alt text, decorative flag, legal fields, download protection/sizes, availability, document category, main logo, preview colour…), ASSET_DELETED, ASSET_PROCESSED (conversion finished), ASSET_MOVED, ASSET_REVISION_ADDED, ASSET_TAG_ADDED/REMOVED, ASSET_CUSTOM_METADATA_UPDATED, ASSET_COLLECTION_ADDED/REMOVED, ASSET_LICENCE_ADDED/REMOVED, ASSET_RELATION_ADDED/REMOVED, ASSET_ATTACHMENT_ADDED/REMOVED, ASSET_VARIANT_ADDED/REMOVED/UPDATED, ASSET_TARGET_CHANGED, WORKFLOW_TASK_ASSIGNED/MOVED/DELETED. Delivered action names are dotted (asset.revision.added, asset.workflow_task.moved…). v1 only has ASSET_CREATE, ASSET_UPDATE, ASSET_DELETE S42. Unverified The v2 changelog announces "23" events; the schema enum lists 24.

• Creating an asset fires created + updated + processed; a new revision fires updated, revision.added, updated, processed S41.

Payload S40: {event: {action, occurredAt, processedAt, sender: {id} | null, payload: [{assetId…}]}, meta: {accountId, webhookId, isSampleEvent}}. Minimal data only — fetch details via GraphQL S36. Bulk actions and same-user/same-action events are bundled into one request S35 S40. accountId + webhookId is globally unique (use it to pick the verification secret) S40.

Delivery & security S37 S38 S39

• HTTPS endpoint with a valid TLS certificate; disable CSRF protection on the receiver.
• Signature header X-Frontify-Webhook-Signature = Base64 of HMAC-SHA256(raw body, webhook secret); compare in constant time.
• Respond 2xx within 5 seconds; redirects are not followed (treated as failure).
• Retries: up to 10, exponential (1 s, 4 s, 16 s, 1 min 4 s, 4 min 16 s, 17 min 4 s, 1 h 8 min, 4 h 33 min, 18 h 12 min, ~3 days); after the last failure the webhook is automatically uninstalled.
• No ordering guarantee; duplicates possible — make processing idempotent.

Other event sources: in-product Automations (triggers → conditions → actions, beta) S112; the Zapier and Tray.io connectors S135 S136. No event stream for guideline or template changes (webhooks cover assets only) S35.

Limits & quirks

SDKs, tools & code samples

Changelog of the API