Integration overview

You can add sign-in to a website or app with Swaymoon Account. Swaymoon Account is an identity provider (IdP) that follows OAuth 2.1 and OpenID Connect. After the user signs in and authorizes on the official domain, your app exchanges an authorization code for tokens and reads user info.

This page is under Swaymoon Developer → Guides → Identifiers. Register and manage clients in the Developer portal. Read Registration and configuration in this directory first.

To view developer docs, turn on Developer Mode in the upper right of Docs.

Document index

Under Identifiers:

Environments and endpoints

For local testing, the Issuer is often http://127.0.0.1:10001; use your environment variables. Always treat URLs in the discovery document as authoritative so you do not hard-code paths that may change.

Common protocol endpoints (Issuer as prefix):

ID Token uses ES256 (elliptic curve) signing. The portal supports three client types, all with PKCE required (S256):

Recommended path

sequenceDiagram
  participant App as Your app
  participant Browser as User browser
  participant Passport as Account

  App->>Browser: 302 redirect to authorize (with PKCE)
  Browser->>Passport: Sign in (if needed)
  Browser->>Passport: Consent to scopes
  Passport->>Browser: 302 redirect to redirect_uri?code=
  Browser->>App: authorization code
  App->>Passport: POST token (code + verifier; confidential also sends Basic; JWT also sends client_assertion)
  Passport->>App: access_token + id_token (confidential and JWT also get refresh_token)
  App->>Passport: GET UserInfo
  Passport->>App: User claims

1. In the Developer portal, register an identifier per Registration and configuration, choosing confidential, public, or JWT assertion. For a confidential client, store the one-time client_secret securely. For JWT assertion, submit only a public key; keep the private key on your server.
2. Implement the authorization-code flow per Authorization code and PKCE (PKCE required).
3. Validate id_token (Issuer, audience, signature, and expiry) and call UserInfo with the Access Token.
4. Use the sub returned by Swaymoon Account as your primary key for the user (pairwise; see Tokens and user info).

Design notes (read first)

• Authorization code + PKCE: portal apps cannot skip code_challenge.
• Confidential client: exchange the code with HTTP Basic (client_id / client_secret) and also send code_verifier.
• Public client: no client_secret. Send client_id and code_verifier in the form when exchanging the code. Do not put a “pretend secret” in the frontend. See Integrate a public client with generative AI and Minimal Python example.
• JWT assertion client: no client_secret. Send client_id, code_verifier, and a client_assertion signed with your private key (ES256). The portal stores only the public key; never upload the private key or put it in the frontend. Concept and trade-offs: Registration and configuration. Request format: Authorization code and PKCE.
• Consent page: the user must explicitly confirm on the authorization page every sign-in (no silent skip). openid is always required. email and profile field scopes can be required, optional, or not requested. Required scopes need a reason and a privacy policy in the portal. When scopes change, the user sees added / removed contrast. Existing production clients do not need code changes for this; new clients should follow the latest Scopes and consent.
• Pairwise sub: the same person gets a different, stable sub under each developer team. Do not use email as the unique primary key.
• Email claim: when email is granted, UserInfo returns an address you can contact. The user may choose a regular email or Hide My Email (a relay; the real address is not given to you). Treat either as a normal email. Use sub as the account primary key.

Compliance and branding

• Sign-in and authorization must go to the official Swaymoon Account domain. Do not build a fake login page to collect passwords.
• Request only the minimum scope your product needs.
• Follow the Swaymoon Account and Developer portal Terms of Use and Anti-Abuse Policy. For developer integration questions, contact hello@swaymoon.com.

Next: after Registration and configuration, implement Authorization code and PKCE.