Operate a safe StoatBoard integration

Web backend

• Use a Confidential Web client and keep its secret in server-side protected storage.
• Generate PKCE S256, state and nonce for every authorization request and bind them to the browser session.
• Exchange the code from the backend with client_secret_basic.
• Store opaque access and refresh tokens encrypted at rest. Never log them.
• Request offline_access only when background continuity is genuinely needed.

Public SPA

• Use a Public SPA client. It has no secret because browser code cannot keep one.
• PKCE S256 is mandatory. Register every exact callback; the token endpoint permits CORS only from origins derived from those registered redirects.
• V1 does not issue refresh tokens to SPAs. Keep short-lived tokens in memory and start a new authorization when needed.
• Do not persist bearer tokens in localStorage or embed them in URLs. A backend-for-frontend is preferable when you need a durable server session.

Move from localhost to production

1. Create separate development and production clients so credentials and revocation stay isolated.
2. Register the full production HTTPS callback, including path and any fixed query string. Wildcards, fragments and userinfo are rejected.
3. Only localhost, 127.0.0.1 and [::1] may use HTTP.
4. Update your public homepage, privacy policy and support destination before sharing the integration.
5. Test behind your real reverse proxy and verify issuer, state, nonce and callback host checks.

Rotate credentials and refresh tokens

Rotating a Web client secret displays the replacement once and immediately revokes the previous credential, authorizations and protocol artifacts for that client. Deploy the new secret as one controlled change; users will need to authorize again.

Refresh tokens rotate on every successful use. Replace the stored token atomically. Reusing an older token revokes its token family and the remembered authorization, so the user must authorize again.

Verify an application domain

1. Choose DNS TXT or the generated HTTPS well-known file proof in the portal.
2. Publish the exact one-time proof and run the check.
3. After domain control succeeds, StoatBoard manually reviews the application identity, site and privacy policy.
4. A material domain, branding or privacy-policy change returns a verified application to pending review and invalidates remembered consent.
5. Manual review accepts only a verified proof for the current homepage domain; an old-domain proof cannot keep the badge.

Unverified applications remain usable. Their consent screen identifies the status, and requesting email adds a stronger warning. Verification improves trust; it is not an official Stoat certification.

Link an existing bot listing

An application can remain standalone or link to one eligible Stoat bot listing owned by the same StoatBoard account. One bot cannot be linked to multiple applications.

Editorial listing status does not automatically disable OAuth. A dedicated security suspension does, and an administrator may suspend both the application and its linked bot in one security action.

Revoke access

• Users can revoke an application from Authorized Apps.
• Applications can call the discovered revocation endpoint for an access or refresh token.
• Deleting or rotating a client revokes its access. Suspending an application revokes all of its clients.
• Unlinking the user's Stoat identity immediately revokes every downstream authorization and token.