Skip to main content
Configure OIDC and durable storage before you start a production Workspaces container. After the first person signs in, create the first API key in the app. Do not insert a key into SQLite.

​
Required settings

Keep secret values in your secret manager or protected environment file. Do not place them in the image, repository, screenshots, or support messages.

​
Configure OIDC

1

Register the client

Create an OpenID Connect client in your identity provider. Register the app origin followed by /auth/callback as its redirect URI.
2

Choose the client type

Use a confidential client when your provider supports it. Workspaces uses PKCE for every login and sends a configured client secret in the token request form.
3

Set the issuer and credentials

Add the issuer, client ID, optional client secret, and cookie secret to the protected container environment.
4

Verify the claims

The ID token must contain a subject and email address. Every signed-in person joins the instance organization as a member.
Production issuers must use HTTPS. If the provider uses a private certificate authority, mount its CA file and set NODE_EXTRA_CA_CERTS to that file inside the container.

​
Configure the public origin

Put a TLS proxy or load balancer in front of port 8790. The browser and proxy must use the exact HTTPS origin in APP_ORIGIN. Register that origin followed by /auth/callback as the OIDC redirect URI. Set TRUST_PROXY=true only when a proxy you control replaces the client IP in the rightmost X-Forwarded-For entry. Leave it false otherwise. PUBLIC_API_ORIGIN defaults to APP_ORIGIN. Set it only when the API uses a different public origin. The container also serves raw files, so leave USERCONTENT_ORIGIN unset unless you operate a separate content origin.

​
Configure storage

Mount one durable local block-storage volume at /data. The directory contains SQLite metadata, Git history, uploaded assets, and live-edit logs.
  • Run one Workspaces process per data directory.
  • Do not use NFS, SMB, EFS, or another shared network filesystem.
  • Make a bind mount writable by user ID 1000.
  • Monitor free disk space. /healthz can still return ok: true while a write fails because the disk is full.

​
Create the first API key

1

Sign in with OIDC

Open the app origin and select Log in. Finish the provider flow.
2

Open API keys

Open Settings > API keys.
3

Create and store the key

Select New key, name it, and store the value in the tool that will use it. Workspaces shows the full key once.
4

Test revocation

Create a separate test key, use it for one request, revoke it, and confirm that the next request returns 401 unauthorized.
Do not create the first key by editing SQLite. Workspaces lists a key only for its signed-in owner, and only that owner can revoke it. A hand-inserted key can work without appearing in the app, leaving no supported way to revoke it.

​
Optional settings

API keys authenticate API, MCP, and read-only Git requests. Removing a person from the identity provider does not revoke their existing keys. Ask each key owner to revoke their keys before you end sign-in access. Before the first update, back up the container and test a restore. Reviewed July 21, 2026. Maintained by the Plannotator documentation team.
Last modified on July 24, 2026