Authentication Flow
Implement OAuth2 sign-in in SPECS Lenses with Auth Kit's Authorization Code and Implicit flows and deep link redirects.
- 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 provides two OAuth2 flows: the Authorization Code flow and the Implicit flow. Both use the
SPECS deep link system to bring the provider's redirect back to your Lens. Choose the flow with the
authenticationType option of the OAuth2 class.
What Auth Kit handles in an OAuth2 flow
The OAuth2 class runs the whole OAuth2 sign-in:
- It builds the authorization URL, and for the Authorization Code flow adds a PKCE code challenge (S256).
- It generates and checks the OAuth2
stateparameter. - It handles the deep link redirect from the OAuth2 provider.
- It exchanges the authorization code for an access token (Authorization Code flow).
- It stores the tokens, keyed by client ID, and refreshes them when they expire. Tokens are saved as JSON in the Lens's persistent storage (see Persistent Storage and Token Management).
Both flows also keep the OIDC id_token when the provider issues one; read it with getIdToken().
Auth Kit Authorization Code flow
The Authorization Code flow is the recommended flow. The provider returns a code, and Auth Kit exchanges it for an access token and, if the provider issues one, a refresh token.
Configure the Authorization Code flow
- 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',
refreshUri: 'https://provider.com/oauth/token', // Optional, defaults to tokenUri
clientSecret: 'your-client-secret', // Optional, for confidential clients
authenticationType: 'code',
});
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',
refreshUri: 'https://provider.com/oauth/token', // Optional, defaults to tokenUri
clientSecret: 'your-client-secret', // Optional, for confidential clients
authenticationType: 'code',
});
Sign in with the Authorization Code flow
Send API requests with InternetModule: Lens scripts have no global
fetch.
const internetModule = require('LensStudio:InternetModule') as InternetModule;
try {
// Start OAuth2 authorization with the scopes you need
const token = await oauth.authorize('read write profile');
if (token) {
print('Authorization successful');
// The token is stored, and getAccessToken() refreshes it when it expires
const accessToken = await oauth.getAccessToken();
// Make an authenticated API request
const response = await internetModule.fetch('https://api.provider.com/user', {
headers: {
Authorization: `Bearer ${accessToken}`,
},
});
const userData = await response.json();
print(`Welcome, ${userData.name}`);
}
} catch (error) {
print(`Authorization failed: ${error.message}`);
}
Auth Kit Implicit flow
The Implicit flow returns the access token directly in the redirect, with no code exchange. Use it
for providers that don't support the Authorization Code flow. The provider issues no refresh token
in this flow, and Auth Kit gives the token a one-hour lifetime. After that, getAccessToken() throws
No refresh token available, and the user has to sign in again. Auth Kit asks the provider to show
the consent screen each time (prompt=consent).
Configure the Implicit flow
tokenUri is still a required option, though the Implicit flow doesn't use it.
const oauth = new OAuth2({
clientId: 'your-client-id',
authorizationUri: 'https://provider.com/oauth/authorize',
tokenUri: 'https://provider.com/oauth/token', // Required, but not used in the Implicit flow
authenticationType: 'implicit',
});
Sign in with the Implicit flow
try {
// The Implicit flow returns the token directly
const token = await oauth.authorize('read write');
if (token) {
print('Authorization successful');
const accessToken = await oauth.getAccessToken();
// Use the access token for API calls
}
} catch (error) {
print(`Authorization failed: ${error.message}`);
}
Related
- Get Started: install Auth Kit and register its redirect URI.
- Token Management: how the tokens from either flow are stored and refreshed.
- Lifecycle: the hand-off between SPECS and the SPECS App during sign-in.
- Third-Party Integration Guide: the Authorization Code flow with Spotify, end to end.