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
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:
- TypeScript
- JavaScript
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
var OAuth2 = require('AuthKit.lspkg/Core/OAuth2').OAuth2;
var 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
oauth.authorize('read write').then(function (token) {
// 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.
Related
- Authentication Flow: where the tokens come from in each flow.
- Get Started: the
OAuth2options, includingrefreshUri. - Persistent Storage: the storage Auth Kit keeps tokens in.