One identity. One file layer.
Here is how to plug into it.

SUITE_REDIRECT_URIS=https://cloud.endorr.com/auth/endorr/callback,http://localhost:3000/auth/endorr/callback \
SUITE_CLIENT_SECRET=<generate with: openssl rand -base64 32> \
pnpm db:seed

{
  "issuer": "https://auth.endorr.com",
  "authorization_endpoint": "https://auth.endorr.com/oauth/authorize",
  "token_endpoint": "https://auth.endorr.com/oauth/token",
  "userinfo_endpoint": "https://auth.endorr.com/oauth/userinfo",
  "revocation_endpoint": "https://auth.endorr.com/oauth/revoke",
  "jwks_uri": "https://auth.endorr.com/.well-known/jwks.json",
  "code_challenge_methods_supported": ["S256"],
  "grant_types_supported": ["authorization_code", "refresh_token"]
}

import { randomBytes, createHash } from 'node:crypto';

const verifier = randomBytes(48).toString('base64url');
const challenge = createHash('sha256').update(verifier).digest('base64url');
const state = randomBytes(16).toString('base64url');
const nonce = randomBytes(16).toString('base64url');
// store { verifier, state, nonce } in the user's pre-login session

const url = new URL('https://auth.endorr.com/oauth/authorize');
url.search = new URLSearchParams({
  response_type: 'code',
  client_id: 'endorr-suite',
  redirect_uri: 'https://cloud.endorr.com/auth/endorr/callback',
  scope: 'openid profile email offline_access organizations files:read files:write account',
  state, nonce,
  code_challenge: challenge,
  code_challenge_method: 'S256',
  // optional: org_id: 'org_…'  → skip the organisation picker
  // optional: prompt: 'select_account' → force the organisation picker
}).toString();
redirect(url);

const res = await fetch('https://auth.endorr.com/oauth/token', {
  method: 'POST',
  headers: {
    'content-type': 'application/x-www-form-urlencoded',
    authorization: 'Basic ' + Buffer.from(`endorr-suite:${process.env.ENDORR_CLIENT_SECRET}`).toString('base64'),
  },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code,                                   // from the callback
    redirect_uri: 'https://cloud.endorr.com/auth/endorr/callback',
    code_verifier: verifier,                // from the pre-login session
  }),
});
const tokens = await res.json();
// { access_token, id_token, refresh_token, token_type: 'Bearer', expires_in: 3600, scope }

import { createRemoteJWKSet, jwtVerify } from 'jose';
const JWKS = createRemoteJWKSet(new URL('https://auth.endorr.com/.well-known/jwks.json'));

const { payload } = await jwtVerify(tokens.id_token, JWKS, { issuer: 'https://auth.endorr.com', audience: 'endorr-suite' });
if (payload.nonce !== expectedNonce) throw new Error('nonce mismatch');
// payload: { sub: 'usr_…', email, email_verified, name, org_id?: 'org_…', auth_time, iat, exp }

const r = await fetch('https://auth.endorr.com/oauth/token', { method: 'POST', headers, body: new URLSearchParams({ grant_type: 'refresh_token', refresh_token }) });
const next = await r.json();       // contains a NEW refresh_token — replace the stored one atomically
// Presenting an already-rotated refresh token revokes the whole family (all tokens from that grant).

GET /v1/me HTTP/1.1
Host: auth.endorr.com
Authorization: Bearer <access_token>
Accept: application/json

https://auth.endorr.com/login?return_to=https://cloud.endorr.com/files
https://auth.endorr.com/signup?return_to=https://cloud.endorr.com/welcome&email=anna@acmeprint.com
https://auth.endorr.com/verify-email?next=https://cloud.endorr.com/

{ "error": { "code": "forbidden", "message": "You do not have permission to do that", "details": null, "request_id": "…" } }

GET /v1/organizations/org_…/members
{ "members": [ { "user_id": "usr_…", "name": "Anna", "email": "anna@acmeprint.com", "email_verified": true, "role": "admin", "joined_at": "…", "you": false } ] }

PUT /v1/folders/fld_…/permissions
{ "principal_type": "team", "principal_id": "tm_…", "role": "editor" }

GET /v1/folders/fld_…/permissions        → manager only
{ "grants": [ { "id": "grant_…", "principal_type": "team", "principal_id": "tm_…", "principal_label": "Prepress", "role": "editor", … } ] }

DELETE /v1/folders/fld_…/permissions/grant_…

POST /v1/files/uploads
{ "folder_id": "fld_…", "name": "front-logo.png", "mime_type": "image/png", "size_bytes": 482113, "storage_class": "temporary" }

201 { "file": { "id": "file_…", "status": "pending", "expires_at": "…", … },
      "upload": { "url": "https://…signed…", "method": "PUT", "headers": { "content-type": "image/png" }, "expires_at": "…" } }

await fetch(upload.url, { method: upload.method, headers: upload.headers, body: fileBlob });
// If you passed size_bytes, the PUT must send exactly that many bytes (it is part of the signature).

POST /v1/files/file_…/complete
{ "sha256": "<hex, optional>", "size_bytes": 482113 }
→ { "file": { "status": "ready", "size_bytes": 482113, … } }

GET  /v1/files/file_…            → metadata, capabilities, path (folder breadcrumb), lineage
POST /v1/files/file_…/download   → { "url": "https://…signed…", "expires_at": "…" }   (viewer)

POST  /v1/folders                     { "name": "Customers", "parent_folder_id": null }
GET   /v1/folders/root/children       → top level of the organisation (folders[] + files[], each with capabilities)
GET   /v1/folders/fld_…/children
PATCH /v1/folders/fld_…               { "name": "…", "parent_folder_id": "fld_…" }   (manager)
DELETE /v1/folders/fld_…              soft delete; everything beneath becomes invisible (manager)

POST /v1/files/file_SOURCE/relationships
{ "derived_file_id": "file_DERIVED", "relationship_type": "pixlpilot_enhancement" }   // or prs_sheet, mockup, …

POST /v1/files/file_…/shares      { "expires_in_days": 7, "max_downloads": 20 }
201 { "share": { "id": "shr_…", "url": "https://auth.endorr.com/s/<token>", "expires_at": "…" } }

GET  /v1/shares/resolve/<token>   anonymous, rate-limited → file metadata + a fresh signed download URL
DELETE /v1/shares/shr_…           revoke (manager)

POST /v1/organizations/org_…/invites   { "email": "anna@acmeprint.com", "role": "member" }   (admin, verified email)
GET  /v1/organizations/org_…/invites   → pending invitations
DELETE /v1/organizations/org_…/invites/inv_…

// lib/endorr.ts (server only)
import { createEndorrAuth } from '@endorr/core-sdk/nextjs';
export const endorrAuth = createEndorrAuth({
  issuer: 'https://auth.endorr.com', clientId: 'endorr-suite', clientSecret: process.env.ENDORR_CLIENT_SECRET!,
  redirectUri: 'https://cloud.endorr.com/auth/endorr/callback', cookieSecret: process.env.ENDORR_COOKIE_SECRET!,
  scope: ['openid', 'profile', 'email', 'offline_access', 'organizations', 'files:read', 'files:write', 'account'],
});

// app/auth/endorr/login/route.ts
export const { GET } = endorrLoginHandler(endorrAuth);

// app/auth/endorr/callback/route.ts
export const { GET } = endorrCallbackHandler(endorrAuth, {
  onSuccess: async ({ tokens, claims, returnTo }) => {
    await sessions.create({ endorrUserId: claims.sub, orgId: claims.org_id, refreshToken: tokens.refresh_token, accessToken: tokens.access_token });
    return Response.redirect(new URL(returnTo, 'https://cloud.endorr.com'), 303);
  },
});

import { EndorrClient } from '@endorr/core-sdk';
const core = new EndorrClient({ baseUrl: 'https://auth.endorr.com', accessToken: () => session.accessToken() });

const me = await core.me.get();
const members = await core.organizations.members(me.organization!.id);
await core.me.changePassword({ current_password, new_password });          // account scope
const { folders, files } = await core.folders.children(null);              // organisation root
await core.permissions.grant('folder', folderId, { principal_type: 'team', principal_id: teamId, role: 'editor' });

import { EndorrProvider, useEndorrUpload } from '@endorr/core-sdk/react';
// <EndorrProvider config={{ baseUrl: '/api/endorr', credentials: 'same-origin' }}> — your BFF proxy adds the bearer token.
const { upload, progress, uploading } = useEndorrUpload();
await upload(file, { folderId });   // create → PUT to storage → complete

# in endorr-auth
cp .env.example .env                      # SECRET_KEY, DATABASE_URL (Postgres on :5433 locally)
pnpm install && pnpm db:migrate
SUITE_REDIRECT_URIS=http://localhost:3000/auth/endorr/callback SUITE_CLIENT_SECRET=dev-suite-secret pnpm db:seed
pnpm dev                                  # https://auth.endorr.com

# in the Suite
ENDORR_ISSUER=https://auth.endorr.com
ENDORR_CLIENT_ID=endorr-suite
ENDORR_CLIENT_SECRET=dev-suite-secret