Overview
Castyr developer docs. Let people sign in to your app, TV or bot with their Castyr account.
Castyr SSO is a standard OAuth 2.0 and OpenID Connect provider at https://sso.castyr.cloud, so any
certified OAuth / OIDC library works with it. You never see anyone's password.
Sign in with Castyr
Web, single-page, mobile and desktop apps: the authorization code flow with PKCE.
TVs, devices and bots
Things without a keyboard: show a code, the user approves on their phone.
Bot SDK
@castyr/bots-auth for Node.js: links, renewal and sign-outs handled for you.
Guide: a Discord bot
A complete discord.js bot that links members' Castyr accounts.
Get started
Register an app
Go to Developers → Register an app (you need a Castyr account) and pick the type that matches where your code runs.
Copy your credentials
Every app gets a client_id. Web apps also get a client_secret, shown once: keep it on your server.
Pick the flow
Follow the guide for your app type from the table below.
Which flow?
| App type | Client | Flow |
|---|---|---|
| Web app (server-side) | Confidential: has a secret | Authorization code (+ PKCE recommended) |
| Single-page app | Public: no secret | Authorization code + PKCE |
| Mobile / desktop app | Public | Authorization code + PKCE, custom scheme or loopback redirect |
| TV / device | Public | Device flow: the user enters a code at /activate |
| Bot | Public | Device flow at /activate/bot. Node bots: the Bot SDK |
Endpoints
Libraries that support discovery only need the issuer; everything else is in the discovery document.
| URL | |
|---|---|
| Issuer | https://sso.castyr.cloud |
| Discovery | https://sso.castyr.cloud/.well-known/openid-configuration |
| Authorize | https://sso.castyr.cloud/oauth/authorize |
| Token | https://sso.castyr.cloud/oauth/token |
| Device code | https://sso.castyr.cloud/oauth/device/code |
| User info | https://sso.castyr.cloud/oauth/userinfo |
| Revoke | https://sso.castyr.cloud/oauth/revoke |
| Signing keys | https://sso.castyr.cloud/.well-known/jwks.json |
Ground rules
- Only
response_type=code. There is no implicit flow and no password grant. - PKCE uses
S256only, and it is required for public clients. - Redirect URIs must match a registered one exactly. No wildcards and no fragments.
- Access tokens last an hour. Refresh tokens rotate on every use.
- Keep your client secret and refresh tokens on your server, never in a web page or app bundle.