Integration Guide

Quick Start with SDK

1. Install the SDK

npm install @zea.cl/thalamus-js

# or with yarn

yarn add @zea.cl/thalamus-js

2. Configure Your Client

Create a Thalamus client instance with your OAuth2 credentials:

import { ThalamusClient } from "@zea.cl/thalamus-js";

const thalamus = new ThalamusClient({

  authUrl: "https://auth.zea.cl",

  clientId: process.env.OAUTH2_CLIENT_ID,

  clientSecret: process.env.OAUTH2_CLIENT_SECRET,

  redirectUri: "https://myapp.com/auth/callback"

});

3. Add Authentication to Your App

The SDK provides simple methods:

• thalamus.auth.getAuthorizationUrl() - Generate login URL with PKCE
• thalamus.auth.exchangeCode() - Exchange authorization code for tokens
• thalamus.auth.refreshToken() - Refresh expired access tokens
• thalamus.tokens.introspect() - Validate and inspect token metadata
• thalamus.tokens.revoke() - Revoke access or refresh tokens

Example: Login Flow

// 1. Generate login URL and redirect user

const { url, state, codeVerifier } = 

  await thalamus.auth.getAuthorizationUrl();

// 2. After callback, exchange code for tokens

const tokens = await thalamus.auth.exchangeCode({

  code: authorizationCode,

  codeVerifier: codeVerifier

});

// 3. Validate token

const info = await thalamus.tokens.introspect(

  tokens.access_token

);

OAuth2 Flows Explained

Authorization Code Flow

The standard OAuth2 flow for web applications:

1. User clicks "Login" - Redirect to /oauth/authorize
2. User authenticates - Enters credentials on Thalamus
3. Authorization code returned - Thalamus redirects to your callback URL
4. Exchange code for tokens - Your backend calls /oauth/token
5. Store tokens securely - Use httpOnly cookies or secure storage

Client Credentials (M2M)

For backend services that need to authenticate without a user, use the getClientCredentialsToken() method with desired scopes.

Token Introspection

Use thalamus.tokens.introspect(token) to validate tokens and retrieve metadata like user_id, scope, and expiration.

Framework Examples

Security Best Practices

Next Steps