API returns 404/401 when using client_credentials OAuth tokens in single-user (Docker) mode

[kyrlon]

Description

I'm running Manyfold via the official Docker image and trying to access the API (models, collections, etc.) using OAuth2 client_credentials tokens.

The OpenAPI spec at /api/v0/openapi.json advertises support for the client_credentials grant with the read scope ("data accessible to the OAuth application's owner"). Token issuance works, but authenticated requests fail.

Note: This occurs in single-user mode (MULTIUSER_MODE not enabled / default Docker setup).

Steps to Reproduce

1. Run Manyfold in single-user mode via Docker (no MULTIUSER=enabled).
2. Log in to the web UI and create a new OAuth application at /oauth/applications (I used the standard confidential application type with read scope).
3. Obtain an access token via the client_credentials grant:

POST /oauth/token
grant_type=client_credentials
client_id=...
client_secret=...
scope=read

→ This succeeds and returns a valid access_token.
4. Use the token to call any API endpoint, e.g.:

• GET /api/v0/collections
• GET /api/v0/models
• or any other endpoint listed in the OpenAPI spec.

Expected behavior:
200 OK response with the requested data (collections/models/etc.).

Actual behavior:

• 401 Unauthorized with body: {"error":"You need to sign in or sign up before continuing."}
  (or 404 Not Found on some endpoints, depending on the route).

[kyrlon]

Resolved — this ended up being a combination of auth mode, token type, request headers, and banging my head talking with claude.

The working setup was:

1. Enable multi-user mode using the correct Docker environment variable:

environment:
  MULTIUSER: enabled

2. Use the correct Accept header for the v0 API:

Accept: application/vnd.manyfold.v0+json

Using Accept: application/json caused 406 Not Acceptable

3. Use a Personal Access Token instead of an OAuth client_credentials token.
   The client_credentials token was issued successfully, but it did not have a resource_owner_id, so it was not associated with a Manyfold user. The API appears to require a user-owned token.

The working solution was to create a Personal Access Token from the Manyfold web UI under:

Profile → Access Tokens

with the needed scopes, such as public and read.

After switching to the Personal Access Token, setting:

Authorization: Bearer <personal_access_token>
Accept: application/vnd.manyfold.v0+json

the API started returning the expected collections/models data.

So the main fixes were:

• MULTIUSER: enabled, not MULTIUSER_MODE: enabled
• use application/vnd.manyfold.v0+json
• use a Personal Access Token rather than client_credentials

Here is my current docker compose yaml file that was used to set this up (WIndows 11):

name: "3d-print-library"
services:
  app:
    image: ghcr.io/manyfold3d/manyfold:latest
    ports:
      - 3214:3214
    volumes:
      # Uncomment to add a filesystem volume for your model library (or multiple if
      # you want multiple libraries), in the form <local_path>:<container_path>.
      # The local path could be a folder that already contains models, in which case Manyfold
      # will scan and import them, or it could be empty.
      # The container path can be anything; you will need to enter it in the "new library" form.
      - E:\Documents\3D Printing\3d_models:/models
      - E:\Documents\3D Printing\libraries:/libraries
    environment:
      DATABASE_ADAPTER: postgresql # mysql2 or sqlite3 are also supported
      DATABASE_HOST: postgres-server
      DATABASE_PORT: 5432 # only needed for non-standard ports
      DATABASE_NAME: manyfold # or the path to the database file if using sqlite3
      DATABASE_USER: manyfold
      DATABASE_PASSWORD: password
      SECRET_KEY_BASE: <SOME SECRET STUFF>
      REDIS_URL: redis://redis-server:6379/1
      PUID: 1000
      PGID: 1000
      MULTIUSER: enabled
      # For details of other optional environment variables, including features such
      # as multiuser mode, visit https://manyfold.app/sysadmin/configuration.html
    restart: unless-stopped
    depends_on:
      - postgres-server
      - redis-server
    networks:
      - manyfold
    # Optional, but recommended for better security
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - DAC_OVERRIDE
      - SETUID
      - SETGID

  postgres-server:
    image: postgres:15
    volumes:
      - db_data:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: manyfold
      POSTGRES_PASSWORD: password
    restart: unless-stopped
    networks:
      - manyfold

  redis-server:
    image: redis:7
    restart: unless-stopped
    networks:
      - manyfold

volumes:
  db_data:

networks:
  manyfold:

Here is the structure of the json credential file used for fetching the data from API:

{
  "client_id": "[CLIENT ID]",
  "client_secret": "[SECRETS_CLIENT]",
  "access_token": "[ACCESS_TOKEN]"
}

Here is a python script with standard libraries fetching the models from the API:

#!/usr/bin/env python3
"""Fetch models from Manyfold API and output a markdown table grouped by collection."""

import argparse
import base64
import json
import os
import sys
import urllib.parse
import urllib.request
import urllib.error
from collections import defaultdict

DEFAULT_BASE_URL = "http://localhost:3214"


def fetch_oauth_token(base_url: str, client_id: str, client_secret: str, debug: bool = False) -> str:
    url = f"{base_url}/oauth/token"
    credentials = base64.b64encode(f"{client_id}:{client_secret}".encode()).decode()
    body = urllib.parse.urlencode({"grant_type": "client_credentials", "scope": "public read"}).encode()
    req = urllib.request.Request(url, data=body, headers={
        "Authorization": f"Basic {credentials}",
        "Content-Type": "application/x-www-form-urlencoded",
    })
    try:
        with urllib.request.urlopen(req) as resp:
            data = json.loads(resp.read().decode())
    except urllib.error.HTTPError as e:
        body_text = e.read().decode()
        print(f"OAuth error {e.code}: {body_text}", file=sys.stderr)
        sys.exit(1)
    except urllib.error.URLError as e:
        print(f"Connection error fetching token: {e.reason}", file=sys.stderr)
        sys.exit(1)
    if debug:
        print(f"Token response: {data}", file=sys.stderr)
    token = data.get("access_token")
    if not token:
        print(f"No access_token in response: {data}", file=sys.stderr)
        sys.exit(1)
    return token


def api_get(base_url: str, path: str, token: str | None, debug: bool = False) -> dict | list:
    url = f"{base_url}{path}"
    req = urllib.request.Request(url, headers={"Accept": "application/vnd.manyfold.v0+json"})
    if token:
        req.add_header("Authorization", f"Bearer {token}")
    if debug:
        print(f"GET {url}  Authorization: Bearer {token[:8]}…", file=sys.stderr)
    try:
        with urllib.request.urlopen(req) as resp:
            return json.loads(resp.read().decode())
    except urllib.error.HTTPError as e:
        body_text = e.read().decode()
        print(f"HTTP error {e.code} fetching {url}: {e.reason}", file=sys.stderr)
        if debug:
            print(f"Response body: {body_text}", file=sys.stderr)
        sys.exit(1)
    except urllib.error.URLError as e:
        print(f"Connection error fetching {url}: {e.reason}", file=sys.stderr)
        sys.exit(1)


def fetch_all_pages(base_url: str, path: str, token: str | None, debug: bool = False) -> list[dict]:
    results = []
    page = 1
    while True:
        sep = "&" if "?" in path else "?"
        data = api_get(base_url, f"{path}{sep}page={page}", token, debug)
        # Manyfold returns Hydra JSON-LD: {"member": [...], "view": {"last": "...?page=N"}}
        if isinstance(data, dict):
            items = data.get("member") or []
            results.extend(items)
            view = data.get("view") or {}
            last = view.get("last") or ""
            # Extract last page number from e.g. "/collections?page=5"
            import re
            m = re.search(r"page=(\d+)", last)
            last_page = int(m.group(1)) if m else 1
            if page >= last_page or not items:
                break
        else:
            break
        page += 1
    return results


def md_table(headers: list[str], rows: list[list[str]]) -> str:
    widths = [max(len(h), max((len(r[i]) for r in rows), default=0)) for i, h in enumerate(headers)]
    sep = "| " + " | ".join("-" * w for w in widths) + " |"
    header_row = "| " + " | ".join(h.ljust(widths[i]) for i, h in enumerate(headers)) + " |"
    lines = [header_row, sep]
    for row in rows:
        lines.append("| " + " | ".join(str(row[i]).ljust(widths[i]) for i in range(len(headers))) + " |")
    return "\n".join(lines)


def model_url(base_url: str, model: dict) -> str:
    mid = model.get("id") or model.get("slug") or ""
    return f"{base_url}/models/{mid}" if mid else ""


def main():
    parser = argparse.ArgumentParser(description="List Manyfold models as a markdown table.")
    parser.add_argument("--url", default=DEFAULT_BASE_URL, help="Manyfold instance base URL")
    parser.add_argument("--token", default=None, help="API bearer token (if required)")
    parser.add_argument("--client-id", default=None, help="OAuth client ID (or set MANYFOLD_CLIENT_ID)")
    parser.add_argument("--client-secret", default=None, help="OAuth client secret (or set MANYFOLD_CLIENT_SECRET)")
    parser.add_argument("--credentials", default="credentials.json", help="JSON file with client_id/client_secret (default: credentials.json)")
    parser.add_argument("--debug", action="store_true", help="Print request/response details for troubleshooting")
    parser.add_argument("--output", default=None, help="Write output to file instead of stdout")
    args = parser.parse_args()

    base_url = args.url.rstrip("/")

    token = args.token
    if not token:
        client_id = args.client_id or os.environ.get("MANYFOLD_CLIENT_ID")
        client_secret = args.client_secret or os.environ.get("MANYFOLD_CLIENT_SECRET")

        if not (client_id and client_secret) and os.path.isfile(args.credentials):
            with open(args.credentials, encoding="utf-8") as f:
                creds = json.load(f)
            token = token or creds.get("access_token") or creds.get("token")
            client_id = client_id or creds.get("client_id")
            client_secret = client_secret or creds.get("client_secret")

        if not token and client_id and client_secret:
            print("Fetching OAuth token…", file=sys.stderr)
            token = fetch_oauth_token(base_url, client_id, client_secret, args.debug)

    print("Fetching collections…", file=sys.stderr)
    collections_raw = fetch_all_pages(base_url, "/collections", token, args.debug)

    print("Fetching all models…", file=sys.stderr)
    all_models = fetch_all_pages(base_url, "/models", token, args.debug)
    all_model_ids = {m.get("@id") for m in all_models}

    # Build groups: fetch models per collection, track which are assigned
    groups: dict[str, list[dict]] = {}
    assigned_ids: set[str] = set()

    for c in collections_raw:
        cid = c.get("@id", "").rstrip("/").split("/")[-1]
        cname = c.get("name") or cid
        print(f"Fetching models for collection '{cname}'…", file=sys.stderr)
        members = fetch_all_pages(base_url, f"/models?collection={cid}", token, args.debug)
        groups[cname] = members
        assigned_ids.update(m.get("@id") for m in members)

    uncategorized = [m for m in all_models if m.get("@id") not in assigned_ids]
    if uncategorized:
        groups["Uncategorized"] = uncategorized

    # Build markdown output
    out_lines: list[str] = ["# Manyfold Models by Collection", ""]

    for coll_name in sorted(groups.keys()):
        out_lines.append(f"## {coll_name}")
        out_lines.append("")

        rows = []
        for m in sorted(groups[coll_name], key=lambda x: x.get("name", "").lower()):
            name = m.get("name") or ""
            url = m.get("@id") or ""
            caption = m.get("caption") or m.get("description") or ""
            if len(caption) > 80:
                caption = caption[:77] + "..."
            mid = url.rstrip("/").split("/")[-1] if url else ""
            rows.append([f"[{name}]({url})" if url else name, caption, mid])

        out_lines.append(md_table(["Model", "Caption", "ID"], rows))
        out_lines.append("")

    output = "\n".join(out_lines)

    if args.output:
        with open(args.output, "w", encoding="utf-8") as f:
            f.write(output)
        print(f"Written to {args.output}", file=sys.stderr)
    else:
        print(output)


if __name__ == "__main__":
    main()

[Floppy]

Glad you got it working! I will check the operation in single-user mode, though TBH it's going to go away soon anyway for security reasons, and will be replaced with an autologin option instead (#5938). I also need to find a way to make it more obvious that the content-type has to be correct, not just application/json. The OpenAPI docs don't make it super clear.