Skip to content
footnote Docs
Install

Agent sign-in settings

The service runs its own login server, so a person’s agent signs in as that person with no key to copy. These are its settings and its keys, for whoever runs the service. How a person connects an agent is in Connect an agent and Connect an agent by hand.

What a sign-in lasts

WhatLastsSetting
An access token10 minutes, renewed by the agentNone
A refresh tokenUntil 7 days unused. Each use replaces itFOOTNOTE_OAUTH_REFRESH_IDLE_HOURS
A connection30 days after sign-inFOOTNOTE_OAUTH_CONNECTION_DAYS
A browser session12 hours unused, or 7 days after sign-inFOOTNOTE_SESSION_IDLE_HOURS and FOOTNOTE_SESSION_MAX_DAYS

When a connection ends, the agent asks the person to sign in again.

The login server settings

SettingDefaultWhat it does
FOOTNOTE_LOGIN_SERVERbuiltinbuiltin runs it here, external trusts another login server, and off turns agent sign-in off: access keys still work, and dev tokens outside production
FOOTNOTE_OAUTH_ISSUERThe origin of MCP_RESOURCE_URLThe issuer of its tokens. It must be that origin
FOOTNOTE_OAUTH_CONSENT_URL/connect/approve on the first web origin on the issuer’s hostThe consent page. It must be on an allowed web origin, on the issuer’s host
FOOTNOTE_OAUTH_SIGNING_KEY_FILE.footnote-oauth-key.pemThe key that signs tokens. Made for you outside production, and required in production
FOOTNOTE_OAUTH_PREVIOUS_KEY_FILESNoneEarlier keys, comma-separated, that still verify after a rotation
FOOTNOTE_OAUTH_DYNAMIC_REGISTRATIONon outside production, off in productionAllows dynamic client registration, which Claude Code uses
FOOTNOTE_OAUTH_REFRESH_IDLE_HOURS168A refresh token unused this long expires
FOOTNOTE_OAUTH_CONNECTION_DAYS30A connection ends this many days after sign-in
MCP_AUTH_ISSUERNoneWith external: whose tokens the MCP server accepts
MCP_AUTH_JWKS_URLNoneWith external: where their keys are
FOOTNOTE_MCP_STATE_KEY_FILE.footnote-mcp-state.keyThe key that seals the questions suggest_context asks in the agent

Addresses must be https, or http on the same computer only.

Make the keys

For production, this makes both keys, readable by their owner only, and keeps a key that exists:

Terminal window
npm run keys:create

In containers, run it in the image, onto the volume that keeps the keys, as Run in production shows.

To make the signing key yourself:

Terminal window
openssl genpkey -algorithm ed25519 -out .footnote-oauth-key.pem && chmod 600 .footnote-oauth-key.pem

The service refuses a key file others may read. Keep it out of the repository, the images and the logs.

The key that seals the questions is at least 32 bytes of hex, and every instance needs the same file. Without it in production, suggest_context lists its questions with a link to the draft instead of asking in the agent.

Terminal window
openssl rand -hex 32 > .footnote-mcp-state.key && chmod 600 .footnote-mcp-state.key

Rotate the signing key

  1. Create a new key, and point FOOTNOTE_OAUTH_SIGNING_KEY_FILE at it.

  2. List the old file, or its public key, in FOOTNOTE_OAUTH_PREVIOUS_KEY_FILES. Make the public key with the command below.

    Terminal window
    openssl pkey -in old.pem -pubout
  3. Restart the service. New tokens use the new key, and tokens signed by the old one work until they expire, ten minutes at most.

  4. Take the old key off the list.

Connections survive a rotation, because refresh tokens are not signed.

If a key leaks. Rotate without listing the old key. Every access token it signed is refused at once, and agents get new ones with their refresh tokens.

Known limits

  • Rate counts live in one process.
  • Agents signed in through another login server, and dev tokens, are not listed in Agents and access.