Fief authentication client.

Example

 const fief = new Fief({
baseURL: 'https://example.fief.dev',
clientId: 'YOUR_CLIENT_ID',
clientSecret: 'YOUR_CLIENT_SECRET',
});

Constructors

Properties

baseURL: string
clientId: string
clientSecret?: string
encryptionKey?: Uint8Array | KeyLike
fetch: {
    (input, init?): Promise<Response>;
    (input, init?): Promise<Response>;
}

Type declaration

    • (input, init?): Promise<Response>
    • Parameters

      • input: RequestInfo | URL
      • Optional init: RequestInit

      Returns Promise<Response>

    • (input, init?): Promise<Response>
    • Parameters

      • input: string | Request | URL
      • Optional init: RequestInit

      Returns Promise<Response>

jwks?: JSONWebKeySet
openIDConfiguration?: Record<string, any>
requestInit?: RequestInit

Methods

  • Return a FiefTokenResponse and FiefUserInfo in exchange of an authorization code.

    Parameters

    • code: string

      The authorization code.

    • redirectURI: string

      The exact same redirectURI you passed to the authorization URL.

    • Optional codeVerifier: string

      The raw PKCE code used to generate the code challenge during authorization.

    • Optional requestInit: RequestInit

      Additional fetch init options. Mostly useful to control fetch cache.

    Returns Promise<[FiefTokenResponse, FiefUserInfo]>

    A token response and user information.

    Example

    const [tokens, userinfo] = await fief.authCallback('CODE', 'http://localhost:8000/callback');
    
  • Return fresh FiefTokenResponse and FiefUserInfo in exchange of a refresh token.

    Parameters

    • refreshToken: string

      A valid refresh token.

    • Optional scope: string[]

      Optional list of scopes to ask for. If not provided, the access token will share the same list of scopes as requested the first time. Otherwise, it should be a subset of the original list of scopes.

    • Optional requestInit: RequestInit

      Additional fetch init options. Mostly useful to control fetch cache.

    Returns Promise<[FiefTokenResponse, FiefUserInfo]>

    A token response and user information.

    Example

    const [tokens, userinfo] = await fief.authRefreshToken('REFRESH_TOKEN');
    
  • Changes the user password with the Fief API using a valid access token.

    An access token with an ACR of at least level 1 is required.

    Parameters

    • accessToken: string

      A valid access token.

    • newPassword: string

      The new password.

    • Optional requestInit: RequestInit

      Additional fetch init options. Mostly useful to control fetch cache.

    Returns Promise<FiefUserInfo>

    Updated user information.

    Example

    userinfo = await fief.changePassword('ACCESS_TOKEN', 'herminetincture')
    
  • Parameters

    • parameters: {
          accessToken?: string;
          code?: string;
          idToken: string;
          jwks: JSONWebKeySet;
      }
      • Optional accessToken?: string
      • Optional code?: string
      • idToken: string
      • jwks: JSONWebKeySet

    Returns Promise<FiefUserInfo>

  • Requests an email change with the Fief API using a valid access token.

    The user will receive a verification code on this new email address. It shall be used with the method emailVerify to complete the modification.

    An access token with an ACR of at least level 1 is required.

    Parameters

    • accessToken: string

      A valid access token.

    • email: string
    • Optional requestInit: RequestInit

      Additional fetch init options. Mostly useful to control fetch cache.

    Returns Promise<FiefUserInfo>

    Updated user information.

    Example

    userinfo = await fief.emailChange('ACCESS_TOKEN', 'anne@nantes.city')
    
  • Verifies the user email with the Fief API using a valid access token and verification code.

    An access token with an ACR of at least level 1 is required.

    Parameters

    • accessToken: string

      A valid access token.

    • code: string
    • Optional requestInit: RequestInit

      Additional fetch init options. Mostly useful to control fetch cache.

    Returns Promise<FiefUserInfo>

    Updated user information.

    Example

    userinfo = await fief.emailVerify('ACCESS_TOKEN', 'ABCDE')
    
  • Return an authorization URL.

    Parameters

    • parameters: {
          codeChallenge?: string;
          codeChallengeMethod?: "plain" | "S256";
          extrasParams?: Record<string, string>;
          lang?: string;
          redirectURI: string;
          scope?: string[];
          state?: string;
      }
      • Optional codeChallenge?: string

        Optional code challenge for PKCE process.

      • Optional codeChallengeMethod?: "plain" | "S256"

        Method used to hash the PKCE code challenge.

      • Optional extrasParams?: Record<string, string>

        Optional object containing specific parameters.

      • Optional lang?: string

        Optional parameter to set the user locale. Should be a valid RFC 3066 language identifier, like fr or pt-PT.

      • redirectURI: string

        Your callback URI where the user will be redirected after Fief authentication.

      • Optional scope?: string[]

        Optional list of scopes to ask for.

      • Optional state?: string

        Optional string that will be returned back in the callback parameters to allow you to retrieve state information.

    Returns Promise<string>

    The authorization URL.

    Example

    const authURL = await fief.getAuthURL({
    redirectURI: 'http://localhost:8000/callback',
    scope: ['openid'],
    );
  • Returns Promise<JSONWebKeySet>

  • Returns a logout URL. If you redirect the user to this page, Fief will clear the session stored on its side.

    You're still responsible for clearing your own session mechanism if any.

    Parameters

    • parameters: {
          redirectURI: string;
      }
      • redirectURI: string

        A valid URL where the user will be redirected after the logout process.

    Returns Promise<string>

    The logout URL.

    Example

    const logoutURL = await fief.getLogoutURL({
    redirectURI: 'http://localhost:8000',
    });
  • Returns Promise<Record<string, any>>

  • Updates user information with the Fief API using a valid access token.

    Parameters

    • accessToken: string

      A valid access token.

    • data: Record<string, any>

      An object containing the data to update.

    • Optional requestInit: RequestInit

      Additional fetch init options. Mostly useful to control fetch cache.

    Returns Promise<FiefUserInfo>

    Updated user information.

    Example

    To update user field values, you need to nest them into a fields object, indexed by their slug.

    userinfo = await fief.update_profile('ACCESS_TOKEN', { fields: { first_name: 'Anne' } })
    
  • Return fresh FiefUserInfo from the Fief API using a valid access token.

    Parameters

    • accessToken: string

      A valid access token.

    • Optional requestInit: RequestInit

      Additional fetch init options. Mostly useful to control fetch cache.

    Returns Promise<FiefUserInfo>

    Fresh user information.

    Example

    userinfo = await fief.userinfo('ACCESS_TOKEN');
    
  • Check if an access token is valid and optionally that it has a required list of scopes, or a required list of permissions.

    Parameters

    • accessToken: string

      The access token to validate.

    • Optional requiredScopes: string[]

      Optional list of scopes to check for.

    • Optional requiredACR: FiefACR

      Optional minimum ACR level required. Read more: https://docs.fief.dev/going-further/acr/

    • Optional requiredPermissions: string[]

      Optional list of permissions to check for.

    Returns Promise<FiefAccessTokenInfo>

    FiefAccessTokenInfo

    Throws

    FiefAccessTokenInvalid if the access token is invalid.

    Throws

    FiefAccessTokenExpired if the access token is expired.

    Throws

    FiefAccessTokenMissingScope if a scope is missing.

    Throws

    FiefAccessTokenMissingPermission if a permission is missing.

    Example

    try {
    accessTokenInfo = await fief.validateAccessToken('ACCESS_TOKEN', ['required_scope']);
    console.log(accessTokenInfo);
    } catch (err) {
    if (err instanceof FiefAccessTokenInvalid) {
    console.error('Invalid access token');
    } else if (err instanceof FiefAccessTokenExpired) {
    console.error('Expired access token');
    } else if (err instanceof FiefAccessTokenMissingScope) {
    console.error('Missing required scope');
    }
    }
  • Parameters

    • response: Response

    Returns Promise<void>