Matrica OAuth SDK

A lightweight SDK for integrating Matrica authentication into your applications.

To get started with Matrica OAuth, visit business.matrica.io or contact us through the website.

Installation

npm install @matrica/oauth-sdk

Version 2.0

Version 2.0.0 of this SDK implements v2 of the Matrica OAuth API. This version introduces significant improvements including pagination, better type safety, enhanced filtering, and improved developer experience.

If you're upgrading from v1, please refer to the Migration Guide for detailed instructions.

Quick Start

import { MatricaOAuthClient } from '@matrica/oauth-sdk';

const client = new MatricaOAuthClient({
    clientId: 'your-client-id',
    clientSecret: process.env.CLIENT_SECRET, // for private apps
    redirectUri: 'http://localhost:3000/callback'
});

app.get('/', async (req, res) => {
  const { url, codeVerifier } = await client.getAuthorizationUrl('profile wallets nfts');

  // Store codeVerifier in the user session here if you plan to exchange the code later
  // req.session.codeVerifier = codeVerifier;

  res.redirect(url);
});

Features

• Easy-to-use OAuth 2.0 authentication flow
• No external runtime dependencies beyond Node 18+ (uses built-in fetch)
• Secure token handling

Authorization Code Flow Explained

The most common way to authenticate users is through the OAuth 2.0 Authorization Code Grant flow. Here's how it works with this SDK:

Step 1: Configure the Client

First, instantiate the client with your application's details. The redirectUri must match the one registered in your Matrica developer settings.

import { MatricaOAuthClient } from '@matrica/oauth-sdk';

const client = new MatricaOAuthClient({
    clientId: 'your-client-id',
    clientSecret: process.env.CLIENT_SECRET, // Include if your app is private/confidential
    redirectUri: 'https://your-app.com/callback' // Your callback endpoint
});

const scope = 'profile email wallets'; // Define requested permissions

Step 2: Generate the Authorization URL and Redirect the User

Create an endpoint in your application (e.g., /login) that generates the unique authorization URL and redirects the user's browser to Matrica. You must store the codeVerifier securely (e.g., in the user's session) as it's needed after the redirect.

app.get('/login', async (req, res) => {
    try {
        const { url, codeVerifier } = await client.getAuthorizationUrl(scope);

        // Store codeVerifier securely in the user's session
        // req.session.codeVerifier = codeVerifier; // Example using express-session

        console.log('Redirecting user to:', url);
        console.log('Storing codeVerifier:', codeVerifier); // For demonstration

        // Redirect the user's browser
        res.redirect(url);
    } catch (error) {
        console.error('Error generating auth URL:', error);
        res.status(500).send('Authentication failed');
    }
});

Step 3: Handle the Callback

After the user logs in and authorizes your application on Matrica, they will be redirected back to your redirectUri (e.g., /callback). Matrica will append an authorization code (and potentially state) as query parameters.

In your callback handler, retrieve the code from the query parameters and the codeVerifier you stored earlier. Use these to exchange the code for access and refresh tokens by creating a UserSession.

// Example using Express.js
app.get('/callback', async (req, res) => {
    const { code, state } = req.query; // Get code from query params
    // const codeVerifier = req.session.codeVerifier; // Retrieve stored codeVerifier

    // --- For Demonstration (replace with session retrieval) ---
    const codeVerifier = 'RETRIEVE_YOUR_STORED_CODE_VERIFIER_HERE';
    console.log('Callback received. Code:', code);
    console.log('Using stored codeVerifier:', codeVerifier);
    // --- End Demonstration ---

    if (!code) {
        return res.status(400).send('Authorization code missing');
    }
    if (!codeVerifier) {
        return res.status(400).send('Code verifier missing from session');
    }

    try {
        // Exchange the code for tokens and create a session
        const userSession = await client.createSession(code as string, codeVerifier);
        console.log('UserSession created successfully!');

        // Store session/tokens securely (e.g., encrypt and store in session/database)
        // req.session.tokens = userSession.getTokens(); // Example

        // Now you can use the session to get user data
        const profile = await userSession.getUserProfile();
        console.log('User Profile:', profile);

        // Redirect user to their dashboard or desired page
        res.redirect('/dashboard');

    } catch (error) {
        console.error('Error exchanging code for tokens:', error);
        res.status(500).send('Authentication failed during token exchange');
    }
});

Step 4: Use the UserSession

Once you have the UserSession (either newly created or reconstructed from stored tokens using client.createSessionFromTokens(tokens)), you can use its methods to access protected resources on behalf of the user.

// Example: Accessing data in another request handler
app.get('/dashboard', async (req, res) => {
    // const tokens = req.session.tokens; // Retrieve stored tokens
    // if (!tokens) {
    //    return res.redirect('/login');
    // }
    // const userSession = client.createSessionFromTokens(tokens);

    // --- For Demonstration (replace with session retrieval) ---
    // Assuming you have a valid session object from the callback step
    // const userSession = ...;
    // --- End Demonstration ---

    try {
        // Example: Fetch user's wallets
        // const wallets = await userSession.getUserWallets();
        // res.render('dashboard', { userProfile: profile, wallets: wallets }); // Pass data to template

        res.send('User authenticated! Check server logs for profile data.'); // Simplified response

    } catch (error) {
        console.error('Error fetching user data:', error);
        res.status(500).send('Failed to fetch user data');
    }
});

Additional Session Helpers

Refreshing Access Tokens

If you stored a refresh token for a confidential application you can refresh the session in-place:

await userSession.refreshToken(); // returns the new TokenResponse and updates the session

Fetching User Domains

Retrieve users' .sol, .eth, or other on-chain domain names with pagination and filtering:

const domains = await userSession.getUserDomains({ skip: 0, take: 20, networkSymbol: 'SOL' });
console.log(domains.data);       // DomainName[]
console.log(domains.pagination); // { count, skip, take }

Generic Social Account Helper

Instead of calling platform-specific helpers you can use a single method:

const twitter  = await userSession.getUserSocial('twitter');
const discord  = await userSession.getUserSocial('discord');
const telegram = await userSession.getUserSocial('telegram');

getUserTwitter, getUserDiscord, and getUserTelegram remain available for convenience.

Examples

Check out the /examples directory for complete implementation examples.

Managing Access Tokens

When using the UserSession methods like getUserProfile(), getUserWallets(), etc., you'll need to handle token expiration yourself. If a token has expired, the API will return an error.

If you need the current access token (e.g., to make a custom API call), you can use getValidAccessToken():

const accessToken = await userSession.getValidAccessToken();
console.log('Current Access Token:', accessToken);

Note that if the token has expired, you'll need to create a new user session by redirecting the user through the authentication flow again.