---
title: "@playstack/client-auth"
description: "PKCE authorization-code clients, credential rotation, and authenticated request retry for extensions, desktop, mobile, and CLI applications."
tags: ["package","identity","oauth","pkce","desktop","mobile","cli","free"]
---

{/* package-access:start */}

> **Free.** MIT licensed. Check preview availability before installing. See [package access](/docs/packages#access-policy).

{/* package-access:end */}

`@playstack/client-auth` is the runtime-neutral public-client half of
Playstack’s authorization-code profile. It never embeds a client secret or owns
the application’s login, MFA, SSO, or consent interface.

{/* package-install:start */}

## Install

After confirming [preview access](/docs/packages#access-policy), install the package at your application's shared Playstack version:

```sh
npm install --save-exact @playstack/client-auth@0.1.0-beta.1
```

Check the peer requirements below before choosing a runtime or provider.

{/* package-install:end */}

## Compose a client

```ts
import {
  createClientAuth,
  createFetchTokenTransport,
} from '@playstack/client-auth'

const auth = createClientAuth({
  clientId: 'desktop-app',
  authorizationEndpoint: 'https://app.example.com/oauth/authorize',
  redirectUri,
  scopes: ['profile', 'devices'],
  transport: createFetchTokenTransport({
    tokenEndpoint: 'https://api.example.com/oauth/token',
    revocationEndpoint: 'https://api.example.com/oauth/revoke',
  }),
  storage: platformCredentialStorage,
  launcher: systemBrowserLauncher,
})

await auth.authorize()
const response = await auth.request(request, apiTransport)
await auth.signOut()
```

Every attempt generates S256 PKCE material and callback state. Completion
verifies the returned state before exchanging the code. Access credentials
refresh before expiry, concurrent refreshes share one operation inside the
configured coordinator, and an authenticated request retries once after an
unauthorized response. A failed refresh clears stored credentials; sign-out
attempts remote revocation and always clears local state.

## Configuration and bridges

| Property | Required | Purpose |
| --- | --- | --- |
| `clientId`, `authorizationEndpoint`, `redirectUri`, `scopes` | Yes | Registered public-client identity and requested authorization. |
| `transport` | Yes | Code exchange, refresh, and optional revocation. |
| `storage` | Yes | Platform-appropriate durable credential storage. |
| `launcher` | For `authorize()` | Opens the system or extension browser and returns the callback URL. |
| `refreshCoordinator` | No | Cross-context or cross-process rotation lock; defaults to one JS process. |
| `pkceCrypto`, `now`, `expirySkewMs` | No | Runtime crypto and deterministic policy overrides. |

`@playstack/client-auth/loopback` is Node-only. It binds `127.0.0.1` on an
ephemeral port, accepts one callback, times out, and closes immediately. Browser
extensions should use `@playstack/extension` for their launcher, credential
storage, and cross-context refresh lock.

## Boundary

The package does not register clients, authorize a user, host an OAuth route,
choose a keychain, or host device authorization endpoints. Those server boundaries
live in `@playstack/auth` and `@playstack/nest-auth`; the host supplies secure
storage and browser-launch behavior.

## Device authorization is available

`@playstack/client-auth/device` exports `beginDeviceAuthorization()`: supply a reviewed transport, display the returned user code/verification URL, then explicitly call `waitForTokens()`. Polling observes slow-down, expiry, cancellation and classified connection timeouts. It does not expose the device code/verifier or introduce a second refresh algorithm.

Server grants use `@playstack/auth/device`; the transport validates token responses and forwards AbortSignal. Successful issuance remains one-time. A lost committed response requires new consent. OS storage and multi-process refresh coordination are yours to verify in the application.

{/* package-reference:start */}

## API entry points and requirements

Reference snapshot: `@playstack/client-auth@0.1.0-beta.1`. Import only the entry point your runtime needs. Paths below are relative to the installed package; use **Go to Definition** in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

| Public entry point | Declaration file |
| --- | --- |
| `@playstack/client-auth` | `./dist/index.d.ts` |
| `@playstack/client-auth/loopback` | `./dist/loopback.d.ts` |
| `@playstack/client-auth/device` | `./dist/device.d.ts` |
| `@playstack/client-auth/testing` | `./dist/testing.d.ts` |
| `@playstack/client-auth/vectors.json` | No TypeScript declaration (asset or metadata export). |
| `@playstack/client-auth/package.json` | No TypeScript declaration (asset or metadata export). |

Node.js engine requirement: `>=20`. This is not a claim that every entry point works in browsers or Workers.

### Peer dependencies

This package declares no peer dependencies. Its ordinary dependencies are resolved by the package manager.

For a complete first program, start with [Getting started](/docs/getting-started). For API lookup and partial-example conventions, see [Reading the reference](/docs/packages#reading-the-reference). Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.

{/* package-reference:end */}