Hyland Nuxeo (Nuxeo Platform) API

Authentication

Basic S2 — Authorization: Basic base64(user:password); the default for API calls S1.

Nuxeo login token S94 S26

1. Call the token servlet (/nuxeo/authentication/token, path from the official Python client) while authenticated (e.g. Basic), with applicationName, deviceId, permission (required) and deviceDescription (optional); a missing required parameter returns 400.
2. The unique token is stored server-side, bound to user + application + device + permission.
3. Send it as X-Authentication-Token: <token> S2. Revocation and expiry rules: Not public.

OAuth 2.0 S4

• Clients are registered by an admin in Web UI → Administration → Cloud Services → Consumers (name, client ID, optional secret, redirect URIs, auto-grant to skip the consent page) or through the REST API (POST/api/v1/directory/oauth2Clients). Nuxeo must run on HTTPS.
• Authorization code: GET/nuxeo/oauth2/authorize?response_type=code&client_id=…[&redirect_uri][&state][&code_challenge&code_challenge_method=S256] → user consent page (oauth2Grant.jsp) unless auto-grant → POST/nuxeo/oauth2/token?grant_type=authorization_code&client_id=…&code=…[&client_secret][&code_verifier].
• JWT bearer: enable with nuxeo.jwt.secret in nuxeo.conf; sign an assertion with HS512 (iss, sub = Nuxeo username); POST/nuxeo/oauth2/token with grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=….
• Refresh: grant_type=refresh_token&client_id=…&refresh_token=….
• Client credentials (machine-to-machine): grant_type=client_credentials&client_id=…&client_secret=…; logs in as the Nuxeo user named like the client ID S4; available since LTS 2025.3 (2025-06-02) S16 S72.
• Use the token as Authorization: Bearer … or ?access_token=… S4.
• OAuth 2 providers, clients and issued tokens can be managed through /api/v1/oauth2/provider|client|token S3.

JWT direct S2 S97 — Authorization: Bearer <JWT> signed with the shared nuxeo.jwt.secret; this is also how the Management API's technical user authenticates.

Browser SSO (SAML 2.0, OIDC, Keycloak, CAS, Kerberos, Shibboleth) belongs to the pluggable authentication chain, configured per server; custom plugins are possible S5.

Core resources

Paths relative to https://{host}/nuxeo/api/v1. Inventory from the REST API documentation S2 S3 S6 S7 S8 S97.

Not exposed as dedicated resources: usage rights/licences (custom schemas), brand portals, asset analytics, webhook subscriptions S3 S2.

Data model

S98 S32 unless noted.

• Document JSON (entity-type: document): uid (UUID), repository, path, type, state (lifecycle), parentRef, isCheckedOut, isVersion, isProxy, proxyTargetId, versionableId, versionLabel, changeToken, isTrashed, title, lockOwner, lockCreated, lastModified, facets[], properties{}, contextParameters{} (filled by enrichers).
• Properties are prefixed by schema: dc:title, dc:description, file:content, picture:views, vid:transcodedVideos, vid:storyboard… The properties header (or X-NXproperties) chooses which schemas are returned (* = all) S9.
• DAM types: Picture (facets Picture, MultiviewPicture; schemas file, picture, image_metadata, iptc), Video (facets Video, HasStoryboard, HasVideoPreview), Audio; facets can be added to custom types S32.
• Blobs are JSON objects (name, mime-type, length, digest, data URL to nxfile) S12 (download URL), S6 (references by upload-batch / upload-fileId).
• Versions: separate immutable documents with major/minor labels; proxies point to a version (publication) S34 S98.
• Taxonomy: folder tree (path), collections (link documents, max 10,000 members by default in LTS 2025 S18), tags, directory-backed vocabulary fields S3.
• Extended fields and enrichers: headers enrichers.document: thumbnail,breadcrumb,children…, fetch.document: dc:creator,… (resolve references), depth, translate.* S9.

Search & querying

Uploads & binaries

Batch upload S6

1. POST/api/v1/upload/new/{handler} (default, or e.g. s3) → batchId. Mandatory even for one file.
2. POST/api/v1/upload/{batchId}/{fileIdx} with Content-Type: application/octet-stream, X-File-Name, X-File-Type (and Content-Length) → 201.
3. Chunked / resumable: same URL with X-Upload-Type: chunked, X-Upload-Chunk-Index (from 0), X-Upload-Chunk-Count, X-File-Size; 202 until all chunks arrive, then 201; GET…/{fileIdx} lists uploadedChunkIds to resume.
4. Attach the file: reference {"upload-batch": batchId, "upload-fileId": "0"} in a document property (file:content) on create/update, or run an operation on the batch (POST/upload/{batchId}/execute/{operationId}, e.g. FileManager.Import). The batch is dropped after execution unless X-Batch-No-Drop: true.

• Chunks are kept in temporary storage until the batch is executed or dropped. Chunk size limit: Not public.

S3 direct upload S13 — with nuxeo.s3storage.useDirectUpload=true, the client gets temporary credentials for a transient bucket, uploads there, and Nuxeo moves the object to the final bucket (Web UI add-on uses this by default when installed).

Downloads S12 S13

• https://{host}/nuxeo/nxfile/{repo}/{docId}[/{xpath or blobholder:N}][/{filename}][?inline=true], e.g. …/file:content, …/files:files/0/file/name.png.
• Picture views and video conversions are blobs inside picture:views / vid:transcodedVideos; REST @rendition/{name} returns named renditions and @convert converts on the fly S8 S32.
• With S3 direct download, Nuxeo redirects to presigned S3 URLs (nuxeo.s3storage.directdownload.expire, default 3,600 s) S13.
• On-the-fly crop/resize/format: optional Dynamic Asset Transformation package (unsupported) S44.

Events & webhooks

• No webhook subscription API. The documented REST endpoints contain no webhook or callback resource S3 S2.
• Server-side events: Nuxeo raises core events (e.g. updatePictureview and videoChanged from the DAM listeners, enrichmentMetadataCreated and similarDocumentsFound from Nuxeo AI) consumed by synchronous or asynchronous listeners; an integrator can make a listener or a Studio-built Automation chain call an external HTTP service S32 S38 Unverified (custom development, not a product feature).
• Nuxeo Stream / Kafka: asynchronous processing (AI pipelines, bulk actions) runs on Nuxeo Stream, which can be backed by Kafka S38 S15; streams can be inspected through the Management API, but no contract for external consumers is documented S97.
• Zapier add-on: lets a Zapier account authenticate with OAuth 2 and subscribe to Nuxeo notifications (default and custom), and run Automation operations; it requires the deprecated JSF UI add-on S58 Unverified (likely legacy).
• Payload format, signing, retries: N/A (no native webhooks).

Limits & quirks

• No API throttling documented: capacity is a sizing question on self-hosted and a contract question on Nuxeo Cloud (usage reports include API activity) S1 S67.
• Scopes ignored: OAuth 2 tokens grant the full rights of the mapped user S4.
• Client credentials require a mirror user named after the client ID S4.
• Two Automation URLs (/nuxeo/site/automation and /nuxeo/api/v1/automation) and two REST prefixes (/nuxeo/api/v1 and /nuxeo/site/api/v1) appear in the docs S10 S8.
• Docs vs reality: the authentication overview still lists NTLM and Portal SSO, but LTS 2025 removed NTLM login and deprecated Portal SSO S5 S15 S16 Unverified (doc lag).
• Removed endpoints still answer through a forwarding filter (nuxeo.forward.deprecated.path.enabled) but should be migrated S15.
• Collection cap of 10,000 documents (LTS 2025; 100,000 in LTS 2023), changed in 2025.6 S18.
• Version-specific behaviour: every customer runs its own LTS and hotfix level; check GET/api/v1/capabilities (distributionVersion) before relying on a feature S3.
• Transaction timeout per call: Nuxeo-Transaction-Timeout header (seconds) S9.
• Swagger explorer may be missing on LTS 2025 servers (optional package) and is unmaintained S15 S23.

SDKs, tools & code samples

Changelog of the API