Documentation Index
Fetch the complete documentation index at: https://mintlify.com/bitwarden/clients/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The Token Service manages access tokens, refresh tokens, API keys, and two-factor tokens. It handles secure storage of authentication credentials across different vault timeout configurations and provides utilities for token validation and decoding.
TokenService
Abstract service for managing authentication tokens.
Observables
hasAccessToken$()
abstract hasAccessToken$(userId: UserId): Observable<boolean>
userId - The user ID to check for an access token
Returns: Observable<boolean> - Observable emitting token presence status
Token Management Methods
setTokens()
abstract setTokens(
accessToken: string,
vaultTimeoutAction: VaultTimeoutAction,
vaultTimeout: VaultTimeout,
refreshToken?: string,
clientIdClientSecret?: [string, string]
): Promise<SetTokensResult>
accessToken - The access token to setvaultTimeoutAction - The action to take when the vault times outvaultTimeout - The timeout for the vaultrefreshToken - Optional refresh token (undefined for CLI Login via API Key flow)clientIdClientSecret - Optional tuple of API Key Client ID and Client Secret
Returns: Promise<SetTokensResult> - Result containing the tokens that were set
Notes:
- For platforms that support secure storage, tokens are stored in secure storage instead of on disk
- This method enforces setting access token and refresh token together for efficiency
clearTokens()
abstract clearTokens(userId?: UserId): Promise<void>
userId - Optional user ID to clear tokens for; if not provided, the active user ID is used
Returns: Promise<void>
setAccessToken()
abstract setAccessToken(
accessToken: string,
vaultTimeoutAction: VaultTimeoutAction,
vaultTimeout: VaultTimeout
): Promise<string>
accessToken - The access token to setvaultTimeoutAction - The action to take when the vault times outvaultTimeout - The timeout for the vault
Returns: Promise<string> - The access token that has been set
Note: For platforms that support secure storage, the access token is stored in secure storage instead of on disk.
clearAccessToken()
abstract clearAccessToken(userId?: UserId): Promise<void>
userId - Optional user ID to clear the access token for; if not provided, the active user is used
Returns: Promise<void>
getAccessToken()
abstract getAccessToken(userId: UserId): Promise<string | null>
userId - The user ID to get the access token for
Returns: Promise<string | null> - The access token or null
getRefreshToken()
abstract getRefreshToken(userId: UserId): Promise<string | null>
userId - The user ID to get the refresh token for
Returns: Promise<string | null> - The refresh token or null
API Key Methods
setClientId()
abstract setClientId(
clientId: string,
vaultTimeoutAction: VaultTimeoutAction,
vaultTimeout: VaultTimeout,
userId?: UserId
): Promise<string>
clientId - The API Key Client ID to setvaultTimeoutAction - The action to take when the vault times outvaultTimeout - The timeout for the vaultuserId - Optional user ID; uses active user if not provided
Returns: Promise<string> - The API Key Client ID that has been set
getClientId()
abstract getClientId(userId: UserId): Promise<string | undefined>
Promise<string | undefined> - The API Key Client ID or undefined
setClientSecret()
abstract setClientSecret(
clientSecret: string,
vaultTimeoutAction: VaultTimeoutAction,
vaultTimeout: VaultTimeout,
userId?: UserId
): Promise<string>
clientSecret - The API Key Client Secret to setvaultTimeoutAction - The action to take when the vault times outvaultTimeout - The timeout for the vaultuserId - Optional user ID; uses active user if not provided
Returns: Promise<string> - The client secret that has been set
getClientSecret()
abstract getClientSecret(userId: UserId): Promise<string | undefined>
Promise<string | undefined> - The API Key Client Secret or undefined
Two-Factor Token Methods
setTwoFactorToken()
abstract setTwoFactorToken(email: string, twoFactorToken: string): Promise<void>
email - The email to set the two-factor token fortwoFactorToken - The two-factor token to set
Returns: Promise<void>
getTwoFactorToken()
abstract getTwoFactorToken(email: string): Promise<string | null>
email - The email to get the two-factor token for
Returns: Promise<string | null> - The two-factor token or null if not found
clearTwoFactorToken()
abstract clearTwoFactorToken(email: string): Promise<void>
email - The email to clear the two-factor token for
Returns: Promise<void>
Token Utility Methods
decodeAccessToken()
abstract decodeAccessToken(tokenOrUserId?: string | UserId): Promise<DecodedAccessToken>
tokenOrUserId - The access token to decode or the user ID to retrieve the access token for; if null, the active user’s token is used
Returns: Promise<DecodedAccessToken> - The decoded access token containing user claims
getTokenExpirationDate()
abstract getTokenExpirationDate(userId: UserId): Promise<Date | null>
Promise<Date | null> - The expiration date or null if token can’t be decoded or has no expiration
tokenSecondsRemaining()
abstract tokenSecondsRemaining(userId: UserId, offsetSeconds?: number): Promise<number>
userId - The user IDoffsetSeconds - Optional seconds to subtract from the remaining time (default: 0). Creates a buffer before actual expiration, useful for preemptive actions
Returns: Promise<number> - The adjusted seconds remaining
tokenNeedsRefresh()
abstract tokenNeedsRefresh(userId: UserId, minutes?: number): Promise<boolean>
userId - The user IDminutes - Optional number of minutes before expiration to consider refreshing (default: 5)
Returns: Promise<boolean> - True if the token needs to be refreshed
getUserId()
abstract getUserId(): Promise<UserId>
Promise<UserId> - The user ID
Deprecated: Use AccountService.activeAccount$ instead
getEmail()
abstract getEmail(): Promise<string>
Promise<string> - The email address
Deprecated: Use AccountService.activeAccount$ instead
getEmailVerified()
abstract getEmailVerified(): Promise<boolean>
Promise<boolean> - True if email is verified
getName()
abstract getName(): Promise<string>
Promise<string> - The user’s name
Deprecated: Use AccountService.activeAccount$ instead
getIssuer()
abstract getIssuer(): Promise<string>
Promise<string> - The token issuer
getIsExternal()
abstract getIsExternal(userId: UserId): Promise<boolean>
userId - The user ID to check
Returns: Promise<boolean> - True if external authentication was used
Security Stamp Methods
getSecurityStamp()
abstract getSecurityStamp(userId?: UserId): Promise<string | null>
userId - Optional user ID; uses active user if not provided
Returns: Promise<string | null> - The security stamp or null
setSecurityStamp()
abstract setSecurityStamp(securityStamp: string, userId?: UserId): Promise<void>
securityStamp - The security stamp to setuserId - Optional user ID; uses active user if not provided
Returns: Promise<void>
Types
DecodedAccessToken
interface DecodedAccessToken {
sub: string; // User ID
email: string; // Email address
email_verified: boolean;
name: string; // Display name
premium: boolean; // Premium status
iss: string; // Issuer
nbf: number; // Not before timestamp
exp: number; // Expiration timestamp
iat: number; // Issued at timestamp
amr: string[]; // Authentication methods
}
SetTokensResult
interface SetTokensResult {
accessToken: string;
refreshToken?: string;
}
Example Usage
Setting Tokens After Login
import { TokenService, VaultTimeoutAction } from '@bitwarden/common';
const tokenService: TokenService;
// Set tokens after successful authentication
const result = await tokenService.setTokens(
accessToken,
VaultTimeoutAction.Lock,
15, // 15 minutes timeout
refreshToken
);
console.log('Tokens set:', result);
Checking Token Expiration
const userId: UserId = await tokenService.getUserId();
// Check if token needs refresh (within 5 minutes of expiration)
const needsRefresh = await tokenService.tokenNeedsRefresh(userId);
if (needsRefresh) {
// Refresh token logic
const secondsRemaining = await tokenService.tokenSecondsRemaining(userId);
console.log(`Token expires in ${secondsRemaining} seconds`);
}
Managing Two-Factor Remember Token
const email = 'user@example.com';
// Save 2FA remember token
await tokenService.setTwoFactorToken(email, 'remember_token_here');
// Retrieve 2FA token on next login
const savedToken = await tokenService.getTwoFactorToken(email);
if (savedToken) {
// Use saved token to bypass 2FA
console.log('2FA can be bypassed with saved token');
}
// Clear 2FA token on logout
await tokenService.clearTwoFactorToken(email);
Decoding Access Token
const userId: UserId = await tokenService.getUserId();
const decoded = await tokenService.decodeAccessToken(userId);
console.log('User info from token:', {
userId: decoded.sub,
email: decoded.email,
name: decoded.name,
premium: decoded.premium,
emailVerified: decoded.email_verified
});
Managing API Keys
const userId: UserId = await tokenService.getUserId();
// Store API key credentials
await tokenService.setClientId(
'client_id',
VaultTimeoutAction.Lock,
null, // Never timeout
userId
);
await tokenService.setClientSecret(
'client_secret',
VaultTimeoutAction.Lock,
null,
userId
);
// Retrieve API key credentials
const clientId = await tokenService.getClientId(userId);
const clientSecret = await tokenService.getClientSecret(userId);