Server-side confidential clients

A confidential client is an app whose server can store a clientSecret securely — a secret never exposed to browsers, mobile apps, or end users. Server-rendered apps, API backends, and background services are typical confidential clients.

If any part of your app runs in a browser or on a user’s device, use PKCE instead. Client secrets in browser code are not secret.

Flow overview

Redirect the browser to Ave

From your server, construct the authorization URL and redirect the user’s browser to https://aveid.net/signin. You can still include PKCE parameters — this is actually recommended even for confidential clients, as defense-in-depth.

Receive the callback on your server

Your server endpoint at the registered redirect_uri receives ?code=...&state=.... Validate state against the value stored in the user’s server session before proceeding.

Exchange the code with your client secret

import { exchangeCodeServer } from "@ave-id/sdk/server";

const tokens = await exchangeCodeServer(
  {
    clientId: process.env.AVE_CLIENT_ID!,
    clientSecret: process.env.AVE_CLIENT_SECRET!,
    redirectUri: "https://yourapp.com/callback",
  },
  { code }
);

Or with raw HTTP:

POST https://api.aveid.net/api/oauth/token
Content-Type: application/json

{
  "grantType": "authorization_code",
  "code": "AUTH_CODE",
  "redirectUri": "https://yourapp.com/callback",
  "clientId": "YOUR_CLIENT_ID",
  "clientSecret": "YOUR_CLIENT_SECRET"
}

Verify the ID token

exchangeCodeServer returns the tokens as Ave sent them. Verify the id_token before creating a session:

import { verifyAveIdToken } from "@ave-id/sdk/server";

const claims = await verifyAveIdToken(tokens.id_token!, { clientId: process.env.AVE_CLIENT_ID! });
if (!claims || claims.nonce !== storedNonce) throw new Error("Invalid id_token");

Store tokens server-side and issue a session

Store access_token, access_token_jwt, id_token, and refresh_token in your encrypted server-side session store. Issue your own session cookie to the browser.Never send raw Ave tokens to the browser — issue your own short-lived session identifier instead.

Refresh silently when tokens expire

import { refreshTokenServer } from "@ave-id/sdk/server";

const newTokens = await refreshTokenServer(
  {
    clientId: process.env.AVE_CLIENT_ID!,
    clientSecret: process.env.AVE_CLIENT_SECRET!,
    redirectUri: "https://yourapp.com/callback",
  },
  { refreshToken: storedRefreshToken }
);

// Replace stored refresh token immediately
await storeRefreshToken(newTokens.refresh_token);

Encryption keys and server callbacks

Encryption keys are delivered in the callback URL fragment, which browsers do not send to servers. A server-rendered callback route receives the code but never the keys. If your app requests an encryption scope, have the callback page read the fragment in client code with extractAppKeyFromUrl or mergeAppEncryptionFromUrl from @ave-id/sdk, keep the keys on the client, and call stripSensitiveFragmentParams(). The code exchange can still happen on your server.

Client secret rules

Store the secret in encrypted runtime config (environment variables, secrets manager)

Never ship clientSecret to browsers, mobile apps, or frontend code

Rotate secrets in the developer portal and your deployment environment at the same time

Log token endpoint failures without logging raw token values or secrets

Handling refresh token rotation

Ave rotates refresh tokens on every use — the old token is immediately invalidated after a successful refresh. If you store the old token and try to reuse it, you’ll get invalid_grant. Best practice:

Store the new refresh_token from every refresh response before discarding the old one
Use a database row lock or atomic update to prevent concurrent refreshes from the same token
If refresh fails with invalid_grant: stop retry loops, clear the session, and force re-authentication

Recommended session architecture

Layer	What it holds
Server session store (encrypted)	`access_token`, `refresh_token`, `id_token`, token expiry
Browser	Short-lived session cookie pointing to server session (HTTP-only, Secure, SameSite=Lax)
Your API	Issues responses based on server-side session lookups — Ave tokens never cross to the client

You can also mint your own short-lived app JWT from the validated Ave id_token and send that to the browser. This decouples your session format from Ave’s token format and gives you full control over expiry and claims.

Encryption

Sign-in

Building on Ave

Frameworks

Server-side confidential clients

Flow overview

Encryption keys and server callbacks

Client secret rules

Handling refresh token rotation

Recommended session architecture

​Flow overview

​Encryption keys and server callbacks

​Client secret rules

​Handling refresh token rotation

​Recommended session architecture

Flow overview

Encryption keys and server callbacks

Client secret rules

Handling refresh token rotation

Recommended session architecture