# @elfsquad/authentication

> The authentication library allows you to easily authenticate with the Elfsquad API.

Latest version **3.1.1** (published 2026-08-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install @elfsquad/authentication
pnpm add @elfsquad/authentication
yarn add @elfsquad/authentication
bun add @elfsquad/authentication
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 3.1.1 |
| Published | 2026-08-25 |
| First published | 2021-08-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 46.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 2 |
| Author | Elfsquad |
| Maintainers | johannesheesterman, yasinatelfsquad |

## Links

- npm: https://www.npmjs.com/package/@elfsquad/authentication
- Repository: https://github.com/Elfsquad/authentication
- Homepage: https://github.com/Elfsquad/authentication#readme
- Issues: https://github.com/Elfsquad/authentication/issues
- npm.io page: https://npm.io/package/@elfsquad/authentication

## Dependencies (1)

- [@openid/appauth](https://npm.io/package/@openid/appauth.md) 1.3.1

## Recent versions

- 3.1.1 (latest) — 2026-08-25
- 3.0.0 — 2026-04-03
- 2.0.10 — 2023-09-14
- 2.0.9 — 2023-04-19
- 2.0.8 — 2023-01-04
- 2.0.7 — 2023-01-03
- 2.0.6 — 2022-09-14
- 2.0.5 — 2022-09-14
- 2.0.4 — 2022-05-04
- 2.0.3 — 2022-05-03
- 2.0.2 — 2022-04-25
- 2.0.1 — 2022-04-25
- 2.0.0 — 2022-03-11
- 1.0.16 — 2022-01-20
- 1.0.15 — 2022-01-11
- … 13 more at https://npm.io/package/@elfsquad/authentication/versions

## README

# Elfsquad Authentication Library

The authentication library allows you to easily authenticate with the Elfsquad API.

## Options

- `clientId` identifier of your OpenIdClient that can be obtained in the integrations page of your [Elfsquad Management System](https://ems.elfsquad.io/integration).
- `redirectUri` callback entry point of your app.
- `scope` (optional) Requested authentication scope. Defaults to `Elfskot.Api offline_access`.
- `loginUrl` (optional) URL of the authentication service. Defaults to `https://login.elfsquad.io`.
- `responseMode` (optional) OAuth response mode, either `'fragment'` or `'query'`. Defaults to `'fragment'`.
- `storeRefreshToken` (optional) Callback to store the refresh token server-side. When provided, the library will call this instead of saving the token to `localStorage`. Must be provided together with `refreshAccessToken` and `revokeRefreshToken`.
- `refreshAccessToken` (optional) Callback to refresh the access token via a server-side endpoint. When provided, the library will call this instead of using the built-in `localStorage`-based refresh flow. Must be provided together with `storeRefreshToken` and `revokeRefreshToken`.
- `revokeRefreshToken` (optional) Callback to revoke the server-side refresh token on sign-out. Must be provided together with `storeRefreshToken` and `refreshAccessToken`.

## Methods

- `signIn` starts the authentication flow.
- `onSignIn` returns a promise that is called after the authentication flow has run successfully.
- `isSignedIn` returns a promise with a boolean result that indicates if the user is signed in.
- `getAccessToken` returns a promise that resolves into access token.

## Examples

```js
import { AuthenticationContext } from "@elfsquad/authentication";

var authenticationContext = new AuthenticationContext({
  clientId: "c2a349a9-02ea-4e1e-a59d-65870529f713",
  redirectUri: "https://example.com",
});

authenticationContext
  .onSignIn()
  .then(() => {
    authenticationContext.getAccessToken().then((accessToken) => {
      console.log("accessToken", accessToken);
    });
  })
  .catch((error) => {
    console.error(error);
  });

authenticationContext.isSignedIn().then((isSignedIn) => {
  if (!isSignedIn) {
    authenticationContext.signIn();
  }
});
```

### BFF pattern (secure refresh token storage)

Use the `storeRefreshToken`, `refreshAccessToken`, and `revokeRefreshToken` callbacks to move refresh tokens out of `localStorage` into server-side HttpOnly cookies, eliminating XSS exposure of long-lived credentials.

```js
import { AuthenticationContext } from "@elfsquad/authentication";

const authenticationContext = new AuthenticationContext({
  clientId: "c2a349a9-02ea-4e1e-a59d-65870529f713",
  redirectUri: "https://example.com",
  storeRefreshToken: (token) =>
    fetch("/auth/store-token", {
      method: "POST",
      body: JSON.stringify({ token }),
    }).then(() => {}),
  refreshAccessToken: () => fetch("/auth/refresh").then((r) => r.json()),
  revokeRefreshToken: () =>
    fetch("/auth/revoke", { method: "POST" }).then(() => {}),
});

authenticationContext.onSignIn().then(() => {
  authenticationContext.getAccessToken().then((accessToken) => {
    console.log("accessToken", accessToken);
  });
});
```

---
_Source: https://npm.io/package/@elfsquad/authentication · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._