Bynder API

Authentication

Where credentials are created S30 S31

1. Bynder Support first enables the feature. An admin then needs the Manage portal settings permission, plus Manage OAuth apps or Manage Bynder permanent tokens.
2. OAuth App: Settings → Advanced Settings → Portal settings → OAuth Apps → Register new application. You enter a name, homepage, description and an integration (from a list or "Other"), then choose the grant type:
   • Authorization Code: set the redirect URLs.
   • Client Credentials: pick an assigned user. Bynder advises a dedicated service user. You also set the CORS domains and the scopes. The Client ID and Secret are returned; the secret is shown once. Scopes cannot be edited later, so create a new app instead. Admins can revoke all refresh tokens of an app or delete it.
3. Permanent token: Portal settings → Permanent Tokens → Add new token (description, integration, assigned user, scopes). The token is displayed once, cannot be edited, and never expires.

OAuth 2.0 endpoints S3 S20

• The reference pages show the token URL with a {authorization} / {refresh} / {client_credentials} suffix. It is a documentation artefact: Bynder asks readers to drop the braces S3.
• Analytics for BI requires OAuth App credentials (client-credentials grant). The KB says permanent tokens are not compatible Unverified S38, yet the Analytics OpenAPI fragments declare only the permanentToken scheme S13.
• Token-based public link access is optional and enabled by Support. An OAuth2 JWT with asset:read unlocks public, DAT and AVS links of limited-use assets, for testing before go-live S54.

Core resources

Paths are relative to https://{tenant}. Endpoint inventory from the OpenAPI fragments S1 and the specific pages cited per row.

Not in the public reference (checked against the index on 2026-09-30) S1:

• saved searches;
• audit or activity log other than Analytics;
• SSO / login configuration;
• permission-profile editing (read-only);
• Waiting Room approvals;
• Studio;
• Print Brand Templates;
• AI Agents configuration.

The Q3.1 2026 release notes announce an "Enrichment Agents API" (up to 10,000 assets per request), but no matching section appears in the public reference S57 Unverified. The scopes table mentions a "Retrieve user specific temporary access token" operation that has no reference page S2 Unverified.

Data model

• Asset (/api/v4/media) fields S4:

  • id (UUID), idHash, name, description, type (image, document, audio, video, 3d), extension[];
  • brandId, userCreated, dateCreated, dateModified, datePublished, copyright, tags[];
  • propertyOptions[] (option ids) and property_{MetapropertyName} keys (option names);
  • archive, limited, isPublic, watermarked, orientation, width, height, fileSize;
  • thumbnails{mini, thul, webimage, …}, mediaItems[] (derivatives/versions when includeMediaItems=true), original (only for public assets with seoBaseUrl configured), transformBaseUrl, videoPreviewURLs[].

  fileName was added in 2025-03 and additionalId in 2025-01 S19.

• Identifiers — two UUID formats S2 S16:

  • v4 endpoints use the ColdFusion 8-4-4-16 form (00000000-0000-0000-0000000000000000);
  • newer /api/... endpoints need standard UUID v4 (8-4-4-4-12), lower-case for similarity search.

• Taxonomy S8 S44:

  • Metaproperties have a unique immutable database name and a translatable label.
  • The type is set at creation. The /api/1 enum is single-select, multi-select, date, text; the upload docs also mention Select2, Autocomplete and Longtext types S5. Only single ↔ multi can be switched later.
  • Options can have dependencies (cascades), access rights and an externalReference. Text values are limited to 2,500 characters.
  • Tags are free text.
  • Smartfilters are UI filter sets built on metaproperties.
  • "Megaproperties" exist for large taxonomies S68.

• Brands / sub-brands partition the Asset Bank. brandId is required when saving an upload S4 S19.

• Collections are user-owned sets of assets, with sharing rights (view, download, watermarked download) S9 S19.

• Files:

  • One asset holds versions (version, active) and media items (derivatives, additional files) S4 S33.
  • Derivatives are account-configured presets, generated automatically on upload S10.
  • DAT derivatives are generated on the fly from transformBaseUrl S11.

• Rights fields — archive/archiveDate, limited/limitedDate (Limited Usage, like an embargo), watermarkDate, isPublic S4:

  • isPublic cannot be reverted once set to true S4.
  • The Beta Asset API adds explicit embargoes and "advanced rights" objects S7.

• Dates: ISO 8601 (yyyy-mm-ddThh:mm:ssZ) S4.

Search & querying

S4 unless noted.

Uploads & binaries

Classic chunked upload (v4) S5 S19

1. GET/api/upload/endpoint: closest S3 endpoint.
2. POST/api/upload/init (filename): returns multipart_params (policy, signature, key, acl…), an upload id and s3_filename.
3. Send each chunk to the S3 accelerate endpoint as multipart/form-data, with upload_id as a form field named id. Parts are ≥ 5 MB except the last. Then register each chunk with POST/api/v4/upload/{uploadId}.
4. Finalise: POST/api/v4/upload/{uploadId}/, or the "additional file" variant.
5. Poll GET/api/v4/upload/poll?items=… until the import id is returned.
6. Save, in one of two ways:
   • as a new asset: POST/api/v4/media/save/{importId} (brandId required; option values preferably by UUID);
   • as a new version: POST/api/v4/media/{id}/save/{importId}.

Announced changes, Q3–Q4 2026 S35: the upload target becomes a Bynder gateway (https://{tenant}/api/1/boss/v4upload/). S3-derived values in the init, chunk and save responses (originalFileS3location, bucket, key) turn into opaque placeholders that must not be used to build URLs. Chunk uploads may be slower. Bynder advises moving to the Asset API (Beta).

• Status on 2026-10-01: the notice is unchanged since 2026-08-06 and still gives no exact date S35. The API reference was re-published on 2026-09-30, but it still documents the S3 hosts (bynder-public-*.s3.amazonaws.com, bynder-public-us-east-1.s3-accelerate.amazonaws.com). It does not mention the gateway S5. The API changelog has no rollout entry S19. Whether a given portal already returns the gateway host can only be checked with credentials, so rollout status is Unknown. Integrations should take the host from the step-1 response instead of hard-coding it Unverified (inferred from S35).

Modern stack upload S6

• Steps: POST/v7/file_cmds/upload/prepare → file_id → POST…/{file_id}/chunk/{n} (application/octet-stream, Content-SHA256 header, chunks numbered from 0) → POST…/{file_id}/finalise_api (fileName, fileSize, chunksCount).
• Used for custom thumbnails (customThumbnailFileId) and workflow-job uploads S4 S19.

Asset API (Beta) S7

• Steps: create an empty draft asset → upload-url (signed) → chunked upload → set metaproperties, tags, embargoes → validate → publish.

Other ingestion: Mass Uploader with a CSV and EXIF/XMP/IPTC fallback; SFTP/S3 bulk import (paid, run by Bynder) S46 S55. Previews are generated up to 50 GB per file and 25,000 px per dimension. Any file type can be stored S45.

Downloads & delivery

• GET/api/v4/media/{id}/download returns a short-lived s3_file URL S10. Required roles:

  • MEDIAHIGHRES;
  • plus ARCHIVEDOWNLOAD for archived assets, DOWNLOADWATERMARK for watermarked ones, KEYVISUALSDOWNLOAD for limited ones.

• Public assets expose permanent CDN derivative URLs (Amazon CloudFront). CloudFront is invalidated automatically when a new version is uploaded S53.

• DAT S11:

  • https://{tenant}/transform/{id}/{name}?io=transform:{operation},{param}:{value};
  • operations: background, crop (with gravity, shape, blur), extend, fill (aspect ratio), fit, and others;
  • default output WebP; format=jpg|png, quality 1–100, focuspoint=x,y.

  DAT needs CX Omnichannel. It supports predictable URLs and presets S68 S58.

• AVS: HLS and MPEG-DASH links for public videos, subtitles, embed code S51 S18.

Events & webhooks

S12 S33

• Configuration: in the UI (Portal Settings → Webhooks) or through the API (webhooks.config:* scopes, Manage Webhooks configurations role). Up to 10 configurations by default; more on request.
• Transport: AWS SNS topic per configuration. Protocols: http, https, email, email-json, sqs (standard queues only; FIFO not supported). Each endpoint must confirm an AWS subscription URL within 48 hours. The confirmation cannot be re-sent: delete the configuration and create it again.
• Events: asset_bank.media.create, asset_bank.media.updated (versions only), asset_bank.media.meta_updated (metadata, restore from archive, first archive), asset_bank.media.archived, asset_bank.media.pre_archived (N days ahead, preArchivedNotificationDays ≥ 1), asset_bank.media.deleted, workflow.job.create, dat.derivative_projection.available, antivirus.scan.failed. Custom events are not possible.
• Payload: JSON with media_id and a media object shaped like the v4 asset. The DAT event carries asset_id, version, prefix. Bynder advises waiting 2–5 s before calling the API back.
• Security:
  • HTTPS endpoints may embed Basic Auth (https://user:pass@host/path); SNS stores the credentials encrypted.
  • No OAuth/JWT signing is planned.
  • GET/v7/webhooks/public/api/ip-ranges returns source IP ranges for allow-listing.
  • Verification of the SNS message signature is not documented by Bynder Unverified.
• Retries / delivery guarantees: Not public (left to SNS; not documented by Bynder).
• The duplicate check rejects the same name + protocol + endpoint combination (HTTP 400) S12.

Limits & quirks

SDKs, tools & code samples

Changelog of the API

Latest first S19 unless noted.