Examples and troubleshooting

Snippets help you match the protocol. Full runnable scripts are in Minimal Python example. Replace constants with your real values.

Discovery document

curl -sS https://api-passport.swaymoon.com/.well-known/openid-configuration | jq .

Confirm fields such as authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri, and id_token_signing_alg_values_supported.

Authorize URL (browser redirect)

https://api-passport.swaymoon.com/oauth2/authorize
  ?response_type=code
  &client_id=swm_YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
  &scope=openid%20name%20picture%20email
  &state=YOUR_STATE
  &code_challenge=YOUR_CHALLENGE
  &code_challenge_method=S256

Encode query parameters only once when you build the URL. If the address bar shows redirect_uri=http%253A%252F%252F…, that is double encoding. The server validates the literal value and fails.

Token exchange: confidential client (curl)

ISSUER=https://api-passport.swaymoon.com
CLIENT_ID='swm_YOUR_CLIENT_ID'
CLIENT_SECRET='YOUR_SECRET'
CODE='...'
VERIFIER='...'
REDIRECT='https://app.example.com/callback'

curl -sS -u "$CLIENT_ID:$CLIENT_SECRET" \
  -X POST "$ISSUER/oauth2/token" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=$CODE" \
  --data-urlencode "redirect_uri=$REDIRECT" \
  --data-urlencode "code_verifier=$VERIFIER"

Token exchange: JWT assertion client (curl)

Sign client_assertion on the backend first (do not put the private key in shell history). Python example:

import time, uuid
from jwcrypto import jwk, jwt  # pip install jwcrypto

key = jwk.JWK.from_json(open("private.jwk.json").read())  # private key with d; do not submit to the portal
now = int(time.time())
token = jwt.JWT(
    header={"alg": "ES256", "kid": key["kid"], "typ": "JWT"},
    claims={
        "iss": "swm_YOUR_CLIENT_ID",
        "sub": "swm_YOUR_CLIENT_ID",
        "aud": "https://api-passport.swaymoon.com/oauth2/token",
        "jti": str(uuid.uuid4()),
        "iat": now,
        "exp": now + 300,
    },
)
token.make_signed_token(key)
assertion = token.serialize()

Then:

ISSUER=https://api-passport.swaymoon.com
CLIENT_ID='swm_YOUR_CLIENT_ID'
CODE='...'
VERIFIER='...'
REDIRECT='https://app.example.com/callback'
ASSERTION='...'   # JWT from the previous step

curl -sS \
  -X POST "$ISSUER/oauth2/token" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=$CODE" \
  --data-urlencode "redirect_uri=$REDIRECT" \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "code_verifier=$VERIFIER" \
  --data-urlencode "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  --data-urlencode "client_assertion=$ASSERTION"

aud must match token_endpoint in the discovery document. To refresh, change grant_type to refresh_token and sign a new assertion (new jti / iat / exp).

Token exchange: public client (curl)

ISSUER=https://api-passport.swaymoon.com
CLIENT_ID='swm_YOUR_CLIENT_ID'
CODE='...'
VERIFIER='...'
REDIRECT='https://app.example.com/callback'

curl -sS \
  -X POST "$ISSUER/oauth2/token" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=$CODE" \
  --data-urlencode "redirect_uri=$REDIRECT" \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "code_verifier=$VERIFIER"

UserInfo (curl)

curl -sS https://api-passport.swaymoon.com/userinfo \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Refresh token (confidential clients)

curl -sS -u "$CLIENT_ID:$CLIENT_SECRET" \
  -X POST "$ISSUER/oauth2/token" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"

FAQ

Integration tips

• Take endpoints from the discovery document; do not hard-code paths.
• Full local scripts: Minimal Python example.
• Sign-in and authorization confirmation happen in the browser. Confidential and JWT assertion clients should exchange tokens and call UserInfo on the server.
• Production Issuer and frontend host are api-passport.swaymoon.com and passport.swaymoon.com.

Getting help

• User docs: turn off Developer Mode, then see the Guides and Legal categories.
• Developer portal: develop.swaymoon.com
• Contact: hello@swaymoon.com (do not send plaintext client_secret through public channels; mask it when you describe a problem)