# piral-oauth2

> Plugin to integrate OAuth 2.0 authentication in Piral.

Latest version **1.12.4** (published 2026-09-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install piral-oauth2
pnpm add piral-oauth2
yarn add piral-oauth2
bun add piral-oauth2
```

## Health

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

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

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.12.4 |
| Published | 2026-09-11 |
| First published | 2020-04-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 97.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1933 |
| Author | smapiot |
| Maintainers | florianrappl, manuel.roemer, lschoett |
| Keywords | piral, pilet-api, smapiot, portal, modules, api, plugin, plugin-user, oauth, oauth2.0, authentication, authorization |

## Links

- npm: https://www.npmjs.com/package/piral-oauth2
- Repository: https://github.com/smapiot/piral
- Homepage: https://piral.io
- Issues: https://github.com/smapiot/piral/issues
- npm.io page: https://npm.io/package/piral-oauth2

## Alternatives

- [@pothos/plugin-authz](https://npm.io/package/@pothos/plugin-authz.md) — 12.4K weekly downloads
- [@bounded-sh/client](https://npm.io/package/@bounded-sh/client.md) — 3.2K weekly downloads
- [@luigi-project/plugin-auth-oauth2](https://npm.io/package/@luigi-project/plugin-auth-oauth2.md) — 2.3K weekly downloads
- [@nocobase/plugin-verification](https://npm.io/package/@nocobase/plugin-verification.md) — 2.0K weekly downloads
- [escher-request](https://npm.io/package/escher-request.md) — 545 weekly downloads

## Recent versions

- 1.12.4 (latest) — 2026-09-11
- 1.12.4-beta.fb90a9c (next) — 2026-10-21
- 0.15.0-alpha.4409 (canary) — 2022-07-07
- 1.12.4-beta.b76e5ae — 2026-10-21
- 1.12.4-beta.5c7192f — 2026-10-17
- 1.12.4-beta.ef95646 — 2026-10-17
- 1.12.4-beta.0bc4ce7 — 2026-10-17
- 1.12.4-beta.cf72637 — 2026-10-17
- 1.12.4-beta.92532b1 — 2026-10-16
- 1.12.4-beta.4f77727 — 2026-10-04
- 1.12.4-beta.6cb8b4e — 2026-10-04
- 1.12.4-beta.dc8413a — 2026-10-04
- 1.12.4-beta.80d7277 — 2026-09-29
- 1.12.4-beta.d019a51 — 2026-09-29
- 1.12.4-beta.6c244e5 — 2026-09-09
- … 924 more at https://npm.io/package/piral-oauth2/versions

## README

[![Piral Logo](https://github.com/smapiot/piral/raw/main/docs/assets/logo.png)](https://piral.io)

# [Piral OAuth 2.0](https://piral.io) · [![GitHub License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/smapiot/piral/blob/main/LICENSE) [![npm version](https://img.shields.io/npm/v/piral-oauth2.svg?style=flat)](https://www.npmjs.com/package/piral-oauth2) [![tested with vitest](https://img.shields.io/badge/tested_with-vitest-99424f.svg)](https://vitest.dev/) [![Community Chat](https://img.shields.io/discord/1222632475449229352)](https://discord.gg/kKJ2FZmK8t)

This is a plugin that only has a peer dependency to `piral-core`. What `piral-oauth2` brings to the table is a direct integration with OAuth 2.0 identity providers on basis of the client-oauth2 library that can be used with `piral` or `piral-core`.

The set includes the `getAccessToken` API to retrieve the current user's access token.

By default, these Pilet API extensions are not integrated in `piral`, so you'd need to add them to your Piral instance.

## Why and When

If you are using authorization with an OAuth 2 provider then `piral-oauth2` might be a useful plugin. It uses the `client-oauth2` library under the hood and exposes token functionality in common HTTP mechanisms (e.g., using `fetch` or a library such as `axios`). Pilets can get the currently available token via the pilet API.

Alternatives: Use a plugin that is specific to your method of authentication (e.g., `piral-auth` for generic user management, `piral-adal` for Microsoft, `piral-oidc` for generic OpenID Connect, etc.) or just a library.

## Documentation

The following functions are brought to the Pilet API.

### `getAccessToken()`

Gets the currently authenticated user's token or `undefined` if no user is authenticated.

## Usage

::: summary: For pilet authors

You can use the `getAccessToken` function from the Pilet API. This returns a promise.

Example use:

```ts
import { PiletApi } from '<name-of-piral-instance>';

export async function setup(piral: PiletApi) {
  const userToken = await piral.getAccessToken();
  // do something with userToken
}
```

Note that this value may change if the Piral instance supports an "on the fly" login (i.e., a login without redirect/reloading of the page).

:::

::: summary: For Piral instance developers

The provided library only brings API extensions for pilets to a Piral instance.

For the setup of the library itself you'll need to import `createOAuth2Api` from the `piral-oauth2` package.

```ts
import { createOAuth2Api } from 'piral-oauth2';
```

The integration looks like:

```ts
import { createOAuth2Api, setupOAuth2Client } from 'piral-oauth2';

const client = setupOAuth2Client({ clientId, ... });

const instance = createInstance({
  // important part
  plugins: [createOAuth2Api(client)],
  // ...
});
```

The separation into `setupOAuth2Client` and `createOAuth2Api` was done to simplify the standard usage.

Normally, you would want to have different modules here. As an example consider the following code:

```ts
// module oauth2.ts
import { setupOAuth2Client } from 'piral-oauth2';

export const client = setupOAuth2Client({ ... });

// app.tsx
import * as React from 'react';
import { createOAuth2Api } from 'piral-oauth2';
import { createInstance } from 'piral-core';
import { client } from './oauth2';
import { render } from 'react-dom';

export function render() {
  const instance = createInstance({
    // ...
    plugins: [createOAuth2Api(client)],
  });
  render(<Piral instance={instance} />, document.querySelector('#app'));
}

// index.ts
import { client } from './oauth2';

if (location.pathname !== '/auth') {
  if (client.account()) {
    import('./app').then(({ render }) => render());
  } else {
    client.login();
  }
}
```

This way we evaluate the current path and act accordingly. Note that the actually used path may be different for your application.

The chosen OAuth 2 flow makes a difference. The example above works fine with the `implicit` flow (default). If you want to use the `code` flow then the integration looks a bit different.

Example integration using the `code` flow:

```ts
// index.ts
import { client } from './oauth2';

if (location.pathname !== '/auth') {
  client.login();
} else {
  client.token().then(
    // all good we are logged in
    () => import('./app').then(({ render }) => render()),
    // something went bad, we should show some error
    () => import('./error').then(({ render }) => render()),
  );
}
```

The code flow will automatically return from `/auth` to `/` once authenticated. Therefore, the application's routing does not have to consider `/auth`, which can remain a special path.

:::

## License

Piral is released using the MIT license. For more information see the [license file](./LICENSE).

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