Getting Started with the AuthPI IdP SDK (server-side)

This guide shows how to integrate AuthPI’s Identity Provider (IdP) into your application for user login, token retrieval, and profile access. It is meant to help you integrate AuthPI on your server-side application using TypeScript. This guide assumes you are familiar with JavaScript/TypeScript and have a basic understanding of OAuth 2.0 and OpenID Connect.

1. Prerequisites

Your runtime needs to support modern JavaScript features. The following runtimes are supported:

  • Node.js - 18.13.0 or later
  • Deno
  • Cloudflare Workers
  • Bun - 1.0 or later

You will need your clientId and clientSecret, plus either an issuerId or a custom domain from AuthPI. Create a client in the AuthPI dashboard to get new credentials. The issuerId or domain identifies the issuer you want to use for authentication and user management.

2. Install the SDK

Install the main package with your package manager of choice. For example, if you are using npm:

npm install @authpi/idp

or if you are using pnpm:

pnpm install @authpi/idp

3. Configure the Client

Initializing

Create a file (e.g., auth.ts) to hold your IdP client instance:

import { IdpClient } from '@authpi/idp';

export const authClient = new IdpClient({
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  issuerId: '123456' // or domain: 'auth.authpi.com'
});
  • clientId: Your client ID from AuthPI.
  • clientSecret: Your client secret from AuthPI. Mandatory for server-side apps, which will need to authenticate with AuthPI’s APIs.
  • issuerId: The ID of the issuer you want to use for authentication.
  • domain: (Optional) If you have a custom domain, you can use it instead of issuerId.

Storage Options

By default, the IdpClient uses an in-memory storage under the hood, which works fine for testing but is not recommended for production. Using persistent storage is recommended if you want to share sessions/tokens between multiple instances or store them securely in a platform’s store. To use a persistent or distributed solution (such as with serverless platforms), you can pass a custom storage property:

import { IdpClient } from '@authpi/idp';
import { MemoryStorage } from '@authpi/utils/storage';

export const authClient = new IdpClient({
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  issuerId: '123456',
  // Or domain: 'auth.example.com',

  storage: new MemoryStorage({ prefix: 'authpi' })
});

Currently support storage options include:

  • MemoryStorage: In-memory storage (default). Not recommended for production.
  • RedisStorage: Redis storage. Use this for distributed environments.
  • CloudflareKVStorage: Cloudflare Workers KV storage. Read our guide on getting started with Cloudflare Workers.
  • CustomStorage: You can implement your own storage provider by implementing the Storage interface.

4. User Log In

Redirect users to AuthPI’s hosted login page. For example, in an Express app:

app.get('/login', async (req, res) => {
  const loginUrl = await authClient.createLoginUrl({
    redirectUri: 'https://yourapp.com/callback',
    scopes: ['profile'],
    usePkce: false
  });
  res.redirect(loginUrl);
});
  • redirectUri: The callback URL in your app to handle the authorization code. This is where AuthPI will send the user after they successfully log in. The URL must match the one you set in the issuer settings in the AuthPI dashboard. The callback will have to be implemented in your app, cf. Step 5.
  • scopes: Tells AuthPI which user info you want and what permissions are needed. If you want the user’s profile, use ['profile'], which will include the user’s scopes. The scope openid is added automatically.
  • usePkce: Enables extra security by generating a code challenge. Default is true.

When a user wants to sign in, you must send them to AuthPI. AuthPI will confirm their credentials and send them back to your callback. You can customize the look and feel of the login page in your dashboard.

5. Handle the Callback

After a successful login, AuthPI redirects the user to your configured redirectUri, appending an authorization code to the URL. Your server must now exchange this code for tokens.

Here’s how to handle the callback in an Express app:

app.get('/callback', async (req, res) => {
  try {
    const callbackUrl = `${req.protocol}://${req.get('host')}${req.originalUrl}`;
    const { agent } = await authClient.exchangeAuthorizationCode(callbackUrl);

    // agent.tokens contains accessToken, idToken, and refreshToken (if enabled)
    // You can now store these tokens in a session or cookie

    res.redirect('/dashboard');
  } catch (err) {
    console.error('Callback error', err);
    res.status(500).send('Failed to authenticate');
  }
});

This step returns an agent—specifically an IdentityAgent, which is a type of AuthenticatedAgent. It provides a unified interface to access the authenticated user’s tokens and profile information.

The agent is your main entry point to work with the logged-in user. It includes:

  • .tokens: Access to the access token, refresh token, and ID token (if available).
  • .profile: A helper to extract user identity info like email, ID, and full profile claims.

You can safely pass the agent around or extract tokens from it to store in your own session system.

For full details, see the AuthenticatedAgent reference in the SDK API reference.

  • Verifies the code and state (if used).

  • Exchanges the code for tokens securely using your client credentials.

  • Returns an IdentityAgent which wraps tokens and provides access to the authenticated user.

Once this step completes, the user is authenticated. You can now grant them access to protected resources in your app.

6. Accessing User Info

To access the authenticated user’s profile:

app.get('/dashboard', async (req, res) => {
  try {
    // If you stored the agent or tokens, you can recreate the IdentityAgent
    // const agent = new IdentityAgent(tokens, authConfig);

    const profile = await agent.profile.full();

    res.send(`Welcome, ${profile.email}`);
  } catch (err) {
    console.error('Access error:', err);
    res.redirect('/login');
  }
});

You can also access just the user ID:

const userId = await agent.profile.id();

7. Refreshing Tokens

If refresh tokens are enabled in your client settings, you can configure auto-refresh:

agent.tokens.autoRefresh = true;

With this enabled, calls to agent.tokens.accessToken() will automatically refresh the token if it is expired.

8. Revoking Tokens

To sign out a user or revoke access tokens:

await agent.tokens.revoke('all');

This ensures tokens can no longer be used and logs out the user from your app.

You now have:

  • A working login flow with AuthPI
  • Secure access and refresh tokens
  • Access to user profile information

From here, you can:

  • Add persistent sessions using SessionManager
  • Protect API routes or backend resources
  • Integrate with frameworks like Hono or platforms like Cloudflare Workers

Explore more in the AuthPI Docs and continue building securely!

AuthPI Documentation