Sign-in for your app
Who may open an app is decided at the edge, before a request reaches it - visitors sign in, teams get the user role, and the app receives who they are in headers and a signed JWT. No sign-in code in the app.
New projects ask visitors to sign in. Only people with a role on the project get in, and every request the app receives says who they are — a header to read, or a JWT to verify. The app itself has no sign-in code, no user table, no sessions to manage; roles are the teams and grants you already have.
Three access modes
| Mode | Who opens the app | What the app receives |
|---|---|---|
Sign-in required (authenticated, the default for new projects; "Who signs in" in the dashboard) | People with a role on the project: teams or people with the user or reader role, and its viewers, developers and admins. Everyone else is asked to sign in, or told which team the app is available to. | Identity on every request |
Public (public; "Anyone" in the dashboard) | Anyone on the internet — a site, a landing page. Projects created before v0.5 are public. | Nothing |
Public, signed-in visitors identified (identified; "Named people" in the dashboard) | Anyone; people who happen to be signed in are identified. A site with a "Hi, Maria" corner. | Identity when there is one |
In identified mode nobody is asked to sign in, so a visitor is identified only once their browser holds the app's cookie: the launcher and the project page's Open button send people through https://<app host>/.shpyrd/signin?rd=/ (silent when they are signed in), and your app can link there itself — "Hello, anonymous visitor — sign in". The examples do exactly that.
shpyrd projects create "Expenses" # sign-in requiredshpyrd projects create "Landing page" --publicshpyrd access --project expenses # who may open itshpyrd access set public --project expenses # anyoneThe dashboard has the same switch on the project's Access page (the "Who may open it" card); making an app public asks for confirmation, and a badge says "Anyone on the internet may open it" while it is.
Who gets in
Grant the user role to a team or a person; viewer, developer and admin open the app too (they already read its logs and configuration):
shpyrd teams create finance --member joao@example.com --group Finance # or a group of your identity providershpyrd members add expenses --team finance --role usershpyrd members add expenses --user pedro@example.com --role userGrant reader for read-only use: the edge refuses every request that changes things (anything but GET, HEAD, OPTIONS and TRACE) and the app receives X-Shpyrd-Roles: reader.
shpyrd members add reports --team everyone --role readerThe built-in everyone team is every person who has signed in: shpyrd members add expenses --team everyone --role user opens the app to the whole company at once.
Someone signed in without a role sees a page saying "Expenses is available to the finance team" (the teams that hold the user role, never people) — with a link to sign in as someone else — instead of the app. Someone who is not signed in is taken to the platform's sign-in page and back to the app afterwards; an API client (nothing in its Accept asks for HTML) gets a JSON 401 with WWW-Authenticate instead. People whose only roles are user see a launcher in the dashboard: tiles for the apps they can open, nothing else.
Scripts, CI and agents
A personal API token (Workspace › API tokens, or shpyrd tokens create) opens a closed app the way its owner would, within the token's roles:
curl -H "Authorization: Bearer shp_…" https://acme-expenses.shpyrd.app/api/reportThe app receives the owner's identity (X-Shpyrd-User, the JWT with sub = the person's id and provider: api-token) and the owner's teams. A token with no role on the project is refused with 403; a revoked one with 401. Any other bearer is treated as anonymous: an authenticated app asks it to sign in, an identified app receives it as sent — so a public app can run its own API authentication behind the door.
Health checks and sign-in
Health checks reach the process directly, bypassing the edge. They have no signed-in user, cookies or identity headers. If your app checks identity itself, exempt its health route from that middleware and return 2xx to a plain GET. Do not redirect the check to /.shpyrd/signin: that route is served by the edge, which the check never reaches.
The default web check uses /. When that path requires sign-in, set processes.web.healthCheck.path: /healthz in shpyrd.yaml and provide an unauthenticated route there, or set processes.web.healthCheck.tcp: true to check only the listening port. Redeploy to apply the change. Startup and liveness failures can restart an otherwise running process; readiness failures keep it out of traffic. See Health checks for the configuration.
What the app receives
Every visitor request through the edge that reaches an app with sign-in required (or an identified visitor of an identified app) carries:
X-Shpyrd-User: joao@example.comX-Shpyrd-Email: joao@example.comX-Shpyrd-Name: João SilvaX-Shpyrd-Teams: finance,everyoneX-Shpyrd-Roles: userAuthorization: Bearer eyJhbGciOiJFZERTQSIs...The headers are set by the platform's edge on every request — whatever a client sends in them is blanked at the front door, for public apps too (since v0.9.4), and replaced with the real values where sign-in is on — and your app is reachable only through that edge (its network policy admits the ingress and nothing else from outside the project). Reading X-Shpyrd-User is enough for most internal apps:
# Flaskwho = request.headers.get("X-Shpyrd-User", "anonymous")teams = request.headers.get("X-Shpyrd-Teams", "").split(",")if "finance" not in teams: abort(403)// Expressconst who = req.get("X-Shpyrd-User") ?? "anonymous";const teams = (req.get("X-Shpyrd-Teams") ?? "").split(",").filter(Boolean);// Gowho := r.Header.Get("X-Shpyrd-User")teams := strings.Split(r.Header.Get("X-Shpyrd-Teams"), ",")Verifying the JWT
For apps that also accept calls from elsewhere, or that want proof rather than a header, the Authorization bearer is a JWT signed by the platform (EdDSA / Ed25519), five minutes long, with the key published at https://shpyrd.<your domain>/.well-known/jwks.json:
{ "iss": "https://shpyrd.example.com", "aud": "expenses", "sub": "idn_01J...", "email": "joao@example.com", "name": "João Silva", "ws": "default", "wsid": "6f1c2a4e-…", "ws_url": "https://shpyrd.example.com", "project": "expenses", "roles": ["user"], "teams": ["finance", "everyone"], "realm": "workspace", "provider": "google", "iat": 1790000000, "exp": 1790000300}Check iss, aud (your project's slug) and exp with any JWT library that supports EdDSA (jose, PyJWT[crypto], github.com/lestrrat-go/jwx). roles holds the caller's role on this project and, for platform admins, their platform role; teams the teams they belong to. wsid is the workspace's id, which stays the same when its address changes; ws_url is its dashboard on its primary domain, for a link back to it.
The keys live at <iss>/.well-known/jwks.json — the issuer is the dashboard URL of the workspace the app belongs to, so the same code works wherever the app runs. Every process is told what to expect through the environment (since v0.9.4):
| Variable | Example | Use |
|---|---|---|
SHPYRD_ISSUER | https://shpyrd.example.com | the expected iss; fetch the JWKS at $SHPYRD_ISSUER/.well-known/jwks.json |
SHPYRD_PROJECT | expenses | the expected aud |
SHPYRD_WORKSPACE | default | the expected ws |
The examples/hello app verifies the token with nothing but the Go standard library (cmd/web/jwt.go: fetch the JWKS, cache it, check the Ed25519 signature by kid, then iss, aud and exp), and its page says whether the visitor was verified or merely read from the headers.
Open as: seeing the app the way a team does
Builders have no test users. On the project's Access page, Open as opens the app in a new tab with a preview identity: your account, but the teams you chose (or none, or Open as nobody for an anonymous visitor); Open as myself ends the preview. It takes the developer role or above. The app sees a member of Finance; the token carries "preview": true and an act claim naming you, so an app can tell if it wants to. Previews are recorded in the project's audit trail.
shpyrd members list expenses # what a team would getHow it works
- The app's Ingress carries ingress-nginx's
auth_requestannotations: every request is checked with the platform's server first (a subrequest, cached for a few seconds). - Signing in happens on the platform's host. The browser is sent there and comes back to the app's host with a one-time code, which becomes a cookie for that app's host only (
__Host-shpyrd_edge). Your app never sees the dashboard's session cookie, and a cookie for one app opens nothing else. - Signing out of the dashboard ends every app cookie: each request checks that the session still exists. Signing out of an app (
/.shpyrd/logouton its host) ends the same session, so the dashboard and every other app close too. - The keys apps verify the JWT against rotate every 30 days; a retired key stays in the JWKS for a week, so verify by
kidand refetch the JWKS when you meet one you do not know (the example's verifier does). - A companion Ingress for
/.shpyrd/on the app's host serves the sign-in bounce, the callback, the sign-out and the "available to team X" page; the path is reserved for the platform. - Self-hosted: operators reach apps with the admin token (
Authorization: Bearer <token>); scripts and CI can too. Pasting the token on the sign-in page opens a browser session the same way accounts do.
Between projects
Projects are network-isolated by default: nothing else running on the cluster may reach an app, even from the same workspace, except the front door, the platform and monitoring. A project opens itself to another with its allow list — on its Connections page, with shpyrd allow add project expenses --project crm, or in shpyrd.yaml:
allow: - project: expenses # expenses may call crm at http://crm.internalThe listed project must be one of the workspace's own: allows never cross a workspace, and the platform refuses a name that is not there. Changes apply within seconds and create no release.
Calling by name
From any instance of a project let in, the callee answers at http://<project>.internal:
const res = await fetch("http://crm.internal/api/customers");Nothing to configure and no token to keep: the name resolves inside the cluster to the platform's internal front door, which knows which project is calling from the address the call comes from, checks the callee's allow list, and passes the call on. http://crm.acme.internal — the project, then the workspace — is the same name written in full, and always valid. The names never leave the cluster; the callee's public hostname still works too, through the front door and the callee's access mode, for a person's identity rather than a project's.
A call that is not admitted is refused at the front door with a JSON body saying why — crm does not let shop in — and counted among the project's denials with the reason service. A callee with no instance ready answers 503 with Retry-After; a sleeping callee is woken by the call like by a visit. The callee's Connections page shows, beside each project let in, how many calls it made in the last day and when the last one was.
Over TLS
Plain HTTP is enough inside the cluster, but a client that insists on https://crm.internal gets it: the name carries a certificate signed by the platform's own CA, which every process is given to trust. The bundle — the public roots plus that CA — is mounted in every process at the path SHPYRD_CA_FILE names (/etc/shpyrd/ca/ca-certificates.crt); Node reads it by itself, through NODE_EXTRA_CA_CERTS. Elsewhere, point the client at the file:
| Runtime | How |
|---|---|
| Node | nothing: NODE_EXTRA_CA_CERTS is set |
| Go | SSL_CERT_FILE=$SHPYRD_CA_FILE in the process's config vars, or load the file into the client's root pool |
| Python (requests, httpx) | REQUESTS_CA_BUNDLE=$SHPYRD_CA_FILE, SSL_CERT_FILE=$SHPYRD_CA_FILE |
| curl | curl --cacert $SHPYRD_CA_FILE https://crm.internal/ |
| Ruby, Java | SSL_CERT_FILE for OpenSSL-based clients; Java imports the file into a truststore |
Who is calling
The callee receives the caller's identity the way it receives a person's: in headers it can read, and in a JWT it can verify.
| Header | Example | Meaning |
|---|---|---|
X-Shpyrd-Service | svc:acme/expenses | the calling project, as svc:<workspace>/<project> |
X-Shpyrd-Caller-Project | expenses | the calling project's slug alone |
Authorization | Bearer eyJ… | a JWT about the caller, five minutes long |
The JWT is signed with the same keys as a person's, published at <iss>/.well-known/jwks.json, and tells the two apart by its realm:
{ "iss": "https://acme.shpyrd.cloud", "sub": "svc:acme/expenses", "aud": "crm", "ws": "acme", "project": "crm", "realm": "service", "roles": [], "teams": [], "iat": 1790000000, "exp": 1790000300}So an app telling people and projects apart reads X-Shpyrd-Service — or verifies the token and reads realm — and treats a request with neither as a person's, or nobody's: the headers are the platform's to set and are dropped from every request that did not go through its edge, so a project cannot claim another's name, and a person cannot claim a project's. The person headers (X-Shpyrd-User and the rest) are never set on a service call.
The platform's own callers are let in the same way: shpyrd allow add platform mcp --project expenses lets the MCP connector call the app directly, and shpyrd allow add platform actions --project expenses lets the shpyrd server call it on a person's behalf. They reach the app by its Service inside the cluster for now; a service identity for them comes with app actions and the MCP server calling apps.