Speckle Authentication Client 🔐

The Speckle Authentication Client makes it easy for web apps to log users into the Speckle platform. It supports two ways to log in: using an OAuth-based application login or a personal access token (PAT). 🌐✅🔑

Installation 🛠️

To install this package, run:

npm install speckle-auth

How to Use It 💡

Logging in with Application Credentials (OAuth) 🔑🌍🛠️

If you're using OAuth, you need a clientId and clientSecret to let users log in.

import { SpeckleAuthClient, type ApplicationOptions } from 'speckle-auth';

const options: ApplicationOptions = {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  serverUrl: 'https://app.speckle.systems',
};
const speckle = new SpeckleAuthClient(options);

async function authenticateUser() {
  const user = await speckle.user();
  if (!user) {
    await speckle.login();
  }
  return user;
}

async function logoutUser() {
  await speckle.logout();
}

Storing Speckle Credentials in cookies

By default, Speckle credentials are stored in local storage. If you want to store them in cookies instead, you can set cookieAppDomain to the domain of your app. This is useful if you want to use the same Speckle credentials across multiple subdomains.

import { SpeckleAuthClient, type ApplicationOptions } from 'speckle-auth';

const options: ApplicationOptions = {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  serverUrl: 'https://app.speckle.systems',
  cookieAppDomain: 'your-app-domain.com',
};

Logging in with a Personal Access Token (PAT) 🔒🛡️🔑

If you don't want to use OAuth, you can log in with a personal access token instead.

import {
  SpeckleAuthClient,
  type PersonalAccessTokenOptions,
} from 'speckle-auth';

const options: PersonalAccessTokenOptions = {
  serverUrl: 'https://app.speckle.systems',
  token: 'your-personal-access-token',
};
const speckle = new SpeckleAuthClient(options);

async function authenticateUser() {
  const user = await speckle.user();
  return user;
}

async function logoutUser() {
  await speckle.logout();
}

API Reference 📚

SpeckleAuthClient(options) 📝

Creates a new authentication client.

• options: You can pass in either ApplicationOptions (for OAuth) or PersonalAccessTokenOptions (for PAT).

speckle.user() 👤🔍💾

Returns the logged-in user, or null if no one is logged in.

speckle.login() 🔑📲✅

Starts the login process for OAuth users. Note that the login will also handle the finish process of the login, when the user is redirected back from Speckle.

speckle.logout() 🚪🔒👋

Logs the user out.

speckle.token 🔑

Returns the current authentication token, or undefined if no token is available. Use it to make further requests to the Speckle API.

License 📜⚖️🔓

This package is available under the MIT License, so you can modify and share it as needed. 🎉📢💡