Documentation Menu

Server-Side Usage

Use OpenAuthsterClient on the server (API routes, Cloudflare Workers, etc.) to verify tokens and access private sessions.

Creating a Server Client

import { createOpenAuthsterClient } from "openauthster-shared/client/user";
 
export function createServerAuth() {
  return createOpenAuthsterClient({
    clientID: "my_project",
    issuerURI: "https://auth.yourdomain.com",
    redirectURI: "https://myapp.com/",
    copyID: null,
    secret: process.env.AUTH_SECRET, // required for private sessions
  });
}

The secret is required to read/write private session data. It should be kept server-side only.

Extracting the Token from a Request

Use setTokenFromRequest(request) to read the Authorization: Bearer … header, verify the authenticity, and set the client's token in one call:

export async function handleRequest(request: Request) {
  const auth = createServerAuth();
 
  await auth.setTokenFromRequest(request);
 
  if (!auth.isAuthenticated) {
    return new Response("Unauthorized", { status: 401 });
  }
 
  // auth is now ready — read sessions, etc.
}

If you just need the raw token string without mutating the client:

const token = auth.getTokenFromRequest(request);

setTokenFromRequest() now verifies the token before accepting it and also falls back to the access_token cookie when the header is missing (v0.2.0).

Reading Private Sessions

export async function GET(request: Request) {
  const auth = createServerAuth();
  await auth.setTokenFromRequest(request);
 
  if (!auth.isAuthenticated) {
    return new Response("Unauthorized", { status: 401 });
  }
 
  const session = await auth.getUserSession("private");
 
  if (session instanceof Error) {
    return new Response(session.message, { status: 500 });
  }
 
  return new Response(JSON.stringify(session), {
    headers: { "Content-Type": "application/json" },
  });
}

Admin user management (v0.2.0)

With a secret you can call the built-in admin helpers (server-side only):

const auth = createServerAuth();
 
await auth.getUsers({ page: 1, limit: 10 });
await auth.getUserById("user_123");
await auth.updateUserById("user_123", { public_session: { theme: "dark" } });
await auth.deleteUserById("user_123");

These wrap the issuer's /users/:clientID and /user/:clientID/:userID endpoints and perform schema validation for you.

Writing Private Sessions

export async function POST(request: Request) {
  const auth = createServerAuth();
  await auth.setTokenFromRequest(request);
 
  if (!auth.isAuthenticated) {
    return new Response("Unauthorized", { status: 401 });
  }
 
  const body = await request.json();
 
  const result = await auth.updateUserSession("private", body);
 
  if (result instanceof Error) {
    return new Response(result.message, { status: 500 });
  }
 
  return new Response(JSON.stringify(result), {
    headers: { "Content-Type": "application/json" },
  });
}

Clearing Private Sessions

export async function DELETE(request: Request) {
  const auth = createServerAuth();
  auth.setTokenFromRequest(request);
 
  if (!auth.isAuthenticated) {
    return new Response("Unauthorized", { status: 401 });
  }
 
  const result = await auth.clearPrivateSession();
 
  if (result instanceof Error) {
    return new Response(result.message, { status: 500 });
  }
 
  return new Response(JSON.stringify(result), {
    headers: { "Content-Type": "application/json" },
  });
}

API Reference

MethodDescription
setTokenFromRequest(req)Reads Authorization: Bearer … and sets the token + isAuthenticated
getTokenFromRequest(req)Returns the bearer token string or null
getUserSession("private")Fetches the private session (needs secret)
updateUserSession("private", data)Merges data into the private session
clearPrivateSession()Replaces private session with {}
getUsers(filters?)Admin: paginated user list (requires secret)
getUserById(user_id)Admin: fetch a single user (requires secret)
updateUserById(user_id, data)Admin: overwrite user fields (requires secret)
deleteUserById(user_id)Admin: remove a user (requires secret)

Next Steps