Operate Auth Dance

The API options include controls for state lifetime, token lifetime, rate limits, token issuer, and lifecycle hooks. Set them at the same boundary as the choreography.

Durations

All duration values are seconds. Flow states, access tokens, and the elevated window default to 300 seconds; refresh tokens default to 86,400 seconds.

const auth = createAuthDance({
  api: {
    ...api,
    durations: {
      sign_in: 300,
      access: 300,
      refresh: 86_400,
      elevated: 300,
    },
  },
});

Refreshing a session does not reopen the elevated window. Enrollment, unenrollment, rotation, subscription, unsubscription, and deletion can raise FRESH_SIGN_IN_REQUIRED after that window closes.

Rate limits

Identity buckets cover verification, message sending, account management, and refresh. Address buckets are consumed by the HTTP layer before route bodies are parsed. Omitted buckets keep the library defaults.

Your storage must include a rate-limiter provider for these counters. The app reads the caller address from cf-connecting-ip, then the first x-forwarded-for entry; a request with neither remains outside address buckets.

Hooks

api.hooks observes identity and session changes, including created, updated, deleted, refreshed, and signed-out events. Hook failures reach onError; the library drops a failure raised by onError itself.

Use hooks for application-side reactions. Keep authorization decisions in the application that consumes the session and identity data.

Tokens and secrets

api.secret is a base64url key used to sign tokens and encrypt flow state. api.tokens.issuer changes the iss claim and the issuer stored in state. Keep the secret stable for every server instance that must read the same flows and tokens.

OpenAPI

Pass info to createAuthDance, then generate a document from the mounted routes.

const schema = await auth.generateOpenAPISchema();

The schema reflects app.basePath and documents the route surface and registered Auth Dance error codes.