Skip to main content

Token Management

Manage OAuth2 tokens in SPECS Lenses with Auth Kit: persistent storage, automatic refresh, expiration, and the OIDC ID token.

  • Snapchat: not supported
  • SPECS: fully supported
  • Camera Kit Web: not supported
  • Camera Kit Mobile: not supported
  • SnapchatNot supported
  • SPECSFully supported
  • Camera Kit WebNot supported
  • Camera Kit MobileNot supported

Platform details

  • Snapchat — Not supported.

  • SPECS — Fully supported.

  • Camera Kit Web — Not supported.

  • Camera Kit Mobile — Not supported.

Auth Kit manages OAuth2 tokens for you: it stores them, restores them in the next session, and refreshes them when they expire, through its Token and TokenManager classes.

How Auth Kit manages tokens

The OAuth2 class handles tokens without extra code: it uses TokenManager to save tokens to persistent storage and to refresh them, and the Token class to represent them. Your Lens works with tokens through authorize(), getAccessToken(), getIdToken(), and signOut().

Auth Kit token storage

Tokens are stored automatically after sign-in

When the sign-in completes, Auth Kit stores the token under the client ID:

import { OAuth2 } from 'AuthKit.lspkg/Core/OAuth2';

const oauth = new OAuth2({
clientId: 'your-client-id',
authorizationUri: 'https://provider.com/oauth/authorize',
tokenUri: 'https://provider.com/oauth/token',
authenticationType: 'code',
});

// Tokens are stored automatically after a successful sign-in
const token = await oauth.authorize('read write');
// The token is now stored under the clientId

Tokens persist across sessions

Auth Kit saves tokens as JSON in the Lens's persistent storage (PersistentStorageSystem store), so they survive between sessions. The OAuth2 constructor restores the stored token for its client ID. To use a different GeneralDataStore, pass it to new TokenManager(storage). For what persistent storage keeps and for how long, see Persistent Storage.

To check for a sign-in from a previous session, call getAccessToken(). isAuthorized is false as soon as the stored access token expires, even when Auth Kit could refresh it, so checking isAuthorized alone sends a returning user through sign-in again.

try {
// Restores the token from the previous session, refreshing it if it has expired
const accessToken = await oauth.getAccessToken();
print('User is already signed in');
} catch (error) {
// No stored token, or the refresh failed
print('User needs to sign in');
await oauth.authorize('required scopes');
}

Auth Kit token refresh

getAccessToken() refreshes the access token when it has expired, using the refresh token and refreshUri (or tokenUri):

const internetModule = require('LensStudio:InternetModule') as InternetModule;

// getAccessToken() refreshes the token if it has expired
const accessToken = await oauth.getAccessToken();

// No refresh logic needed in your Lens
const response = await internetModule.fetch('https://api.provider.com/user', {
headers: {
Authorization: `Bearer ${accessToken}`,
},
});

To refresh before the token expires, call refreshToken(). Both throw No refresh token available when there is no refresh token, as after the Implicit flow.

Token expiration handling

The Token class computes the expiration time with a one-minute buffer, so Auth Kit refreshes a token a minute before the provider's expiry. When the provider doesn't send expires_in, Auth Kit uses 3600 seconds.

Auth Kit token structure

Token class

The Token class represents an OAuth2 token with these properties:

// Token interface
interface IToken {
access_token: string;
refresh_token: string | null;
expires_in: number;
expiration_timestamp: number;
id_token?: string | null;
}

// Auth Kit creates Token instances during sign-in;
// you don't create them yourself

Token.toString() masks the token values, keeping the first and last four characters, so tokens printed to the logs aren't leaked in full.

OIDC ID token

When the provider is an OpenID Connect provider and you request the openid scope, Auth Kit keeps the id_token from the sign-in and from each refresh. getIdToken() returns it, or null when the provider issued none. It doesn't refresh the token: call getAccessToken() first when you need the ID token in sync with a refreshed access token.

await oauth.getAccessToken();
const idToken = oauth.getIdToken();

TokenManager class

The TokenManager class saves tokens to persistent storage, restores them, clears them on sign-out, and refreshes them through the token endpoint.