> ## Documentation Index
> Fetch the complete documentation index at: https://docs.renaiss.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Sign in with Renaiss (SSO)

> Add Renaiss as an OpenID Connect identity provider so users can sign in to your app with their Renaiss account.

**Sign in with Renaiss** lets your application authenticate users with their existing
Renaiss account using the standard **OpenID Connect (OIDC)** authorization-code flow with
PKCE. Once integrated, you receive a verified identity token containing the user's profile,
email, wallet, and linked-social claims.

<Info>
  **There is no self-service partner portal yet.** App registration is handled manually by
  the Renaiss team. To get a `client_id`, a `client_secret`, and your redirect URI added to
  the allowlist, [reach out to the team](#get-help). That's also how you sign in to manage
  your client for now.
</Info>

## How it works

Renaiss is a confidential OIDC provider. Your integration follows the standard pattern:

<Steps>
  <Step title="Register your app with the team">
    Send the team your app name and the exact redirect URI(s) you'll use. They provision a
    client and hand back your `client_id` and `client_secret` over a secure channel.
  </Step>

  <Step title="Discover the endpoints">
    Point your OIDC client at the discovery document and it derives the authorize, token,
    userinfo, and JWKS endpoints automatically.
  </Step>

  <Step title="Run the authorization-code + PKCE flow">
    Redirect the user to Renaiss to consent, exchange the returned `code` for tokens, and
    verify the `id_token`.
  </Step>

  <Step title="Read the user's claims">
    Use the verified claims from the `id_token` (or call the userinfo endpoint).
  </Step>
</Steps>

## Prerequisites

Before you begin, you need:

* A `client_id` and `client_secret` issued by the Renaiss team (see the callout above).
* One or more **exact** redirect URIs registered on the allowlist.
* An OIDC client library. Examples below use Node's [`openid-client`](https://github.com/panva/node-openid-client),
  but any compliant OIDC library works.

<Warning>
  The `client_secret` is a password. Keep it **server-side only**: never ship it to the
  browser or commit it to a repository. Share it only over a secure channel. Renaiss stores
  it hashed, so if it leaks, email [info@renaiss.xyz](mailto:info@renaiss.xyz) to rotate it.
</Warning>

## Configuration

Provide your integration with the following settings. Replace the bracketed values with the
credentials and redirect URI the team gave you.

```bash .env theme={null}
# Renaiss SSO
RENAISS_ISSUER=https://www.renaiss.xyz/api/auth
RENAISS_CLIENT_ID=<your-client-id>
RENAISS_CLIENT_SECRET=<your-client-secret>
RENAISS_REDIRECT_URI=https://your-app.example.com/auth/callback
RENAISS_SCOPE=openid profile email safe x
```

The discovery document is always `${RENAISS_ISSUER}/.well-known/openid-configuration`. Point
your OIDC client at that URL and it resolves the rest of the endpoints for you.

### Client settings

Your client is provisioned as a **confidential** client with these defaults:

| Setting             | Value                                                                                                                            |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Grant types         | `authorization_code`, `refresh_token`                                                                                            |
| PKCE                | **Required** (`code_challenge_method=S256`)                                                                                      |
| Token endpoint auth | `client_secret_post` (secret sent in the token request body)                                                                     |
| Consent screen      | Forced every sign-in with `prompt=consent`; otherwise only on first authorization (see [below](#controlling-the-consent-screen)) |

### Choosing an issuer

The `RENAISS_ISSUER` determines which environment you authenticate against. Use the value the
team gives you during onboarding:

| Your setup                          | `RENAISS_ISSUER`                   |
| ----------------------------------- | ---------------------------------- |
| **Production**                      | `https://www.renaiss.xyz/api/auth` |
| **Dev / preview**                   | Provided by the team               |
| Renaiss running **locally** (:3000) | `http://localhost:3000/api/auth`   |

<Note>
  Only `localhost` may use plain `http`. All deployed issuer hosts are HTTPS-only.
</Note>

### Redirect URI must match exactly

Renaiss uses an exact-match, anti-phishing allowlist with **no wildcards, trailing slashes, or
port changes**. The redirect URI your app sends must be byte-for-byte identical to a
registered one.

Need to add or change a URL (a new port, a deployed `https://...` callback, etc.)? Send it to
the team to allowlist. Registering it only on your side is not enough.

### Controlling the consent screen

Add `prompt=consent` to the authorize request to force the consent screen on **every** sign-in.
Omit it and the user sees consent **only the first time** they authorize your app:

```
${RENAISS_ISSUER}/oauth2/authorize?...&prompt=consent
```

## Quick start

Using Node and `openid-client`:

<Steps>
  <Step title="Discover the provider">
    Load `${RENAISS_ISSUER}/.well-known/openid-configuration` to configure your client.
  </Step>

  <Step title="Build the login route">
    Generate a PKCE `code_verifier` / `code_challenge` (S256), a random `state`, and a
    `nonce`. Stash them in the session, then redirect to the authorize endpoint with
    `scope=openid profile email safe x` (add `prompt=consent` to force the consent screen
    on every sign-in).
  </Step>

  <Step title="Handle the callback">
    At your redirect path, verify `state`, exchange the `code` at the token endpoint (secret
    in the request body), and verify the `id_token` signature against the JWKS, checking
    `iss`, `aud`, `exp`, and `nonce`.
  </Step>

  <Step title="Read the claims">
    Read the user's claims from the verified `id_token`, or call the userinfo endpoint.
  </Step>
</Steps>

<Tip>
  A complete, dependency-light reference implementation using `openid-client` is available
  from the team on request during onboarding.
</Tip>

## What you get back

These claims are returned in the `id_token` and from the userinfo endpoint, gated by the
scopes you requested:

| Claim                                                      | Scope     | Notes                                                                      |
| ---------------------------------------------------------- | --------- | -------------------------------------------------------------------------- |
| `sub`                                                      | `openid`  | **Opaque, stable** user id. Key your records on it; don't parse it         |
| `name`, `picture`                                          | `profile` |                                                                            |
| `email`, `email_verified`                                  | `email`   |                                                                            |
| `safe_wallet_address`, `chain_id`, `legacy_wallet_address` | `safe`    | `safe_wallet_address` **may be `null`** ("wallet not ready"), not an error |
| `twitter_username`                                         | `x`       | Cached X handle, or `null` if the user hasn't linked X                     |

**Behaviors to handle:**

* **`sub`** is opaque and stable, so store and key on it; never parse it for meaning.
* **`safe_wallet_address: null`** means the wallet isn't ready yet. Show a soft retry/empty
  state; do **not** hard-fail the login.
* Always **verify the `id_token`** signature plus `iss` / `aud` / `exp` / `nonce`. A compliant
  OIDC library does this for you.

## Token exchange smoke test

Once you have an authorization `code` and the matching `code_verifier`, you can exchange them
directly to sanity-check your client:

```bash theme={null}
curl -s -X POST "$RENAISS_ISSUER/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code="$AUTH_CODE" \
  -d code_verifier="$CODE_VERIFIER" \
  -d client_id="$RENAISS_CLIENT_ID" \
  -d client_secret="$RENAISS_CLIENT_SECRET" \
  -d redirect_uri="$RENAISS_REDIRECT_URI"
```

A successful response returns an `access_token`, `id_token`, and (if requested) a
`refresh_token`.

## Get help

App registration, credentials, redirect-URI changes, and secret rotation are all handled by
the Renaiss team while the self-service portal is in progress.

<Card title="Email info@renaiss.xyz" icon="mail" href="mailto:info@renaiss.xyz">
  Reach out to register your app, get your credentials, or add a new redirect URI to the
  allowlist. We'll turn it around quickly.
</Card>