@wocha/angular

Angular service, guard, and callback component for Wocha authentication in single-page applications. Implements the OAuth 2.0 authorisation code flow with PKCE as a public client — no client secret required.

Install

npm install @wocha/angular
# or: pnpm add / yarn add @wocha/angular

Peer dependencies: Angular 17+, @angular/router, and RxJS 7+.

Quick start

Import WochaAuthModule.forRoot() in your app module and register a /callback route:

// app.config.ts or app.module.ts
import { WochaAuthModule } from "@wocha/angular";

WochaAuthModule.forRoot({
  issuer: "https://my-tenant.auth.wocha.ai",
  clientId: "your-client-id",
  redirectUri: window.location.origin + "/callback",
});

// app.routes.ts
import { GreetCallbackComponent, wochaAuthGuard } from "@wocha/angular";

export const routes = [
  { path: "callback", component: GreetCallbackComponent },
  { path: "dashboard", canActivate: [wochaAuthGuard], loadComponent: () => import("./dashboard") },
];

Register your redirect URI (https://your-app.com/callback) in the Wocha Console before testing.

Configuration reference

| Field | Type | Required | Description | |-------|------|----------|-------------| | issuer | string | Yes | OIDC issuer URL (e.g. https://my-tenant.auth.wocha.ai). | | clientId | string | Yes | OAuth client ID for your SPA application. | | redirectUri | string | No | Callback URL. Defaults to {origin}/callback. | | scopes | string | No | Space-separated scopes. Default: openid profile email offline_access. | | audience | string | No | API audience claim, if your tenant requires it. | | platformApiUrl | string | No | Platform API base URL for permission checks. |

WochaAuthService

Inject WochaAuthService for reactive auth state and imperative actions:

import { Component, inject, OnInit } from "@angular/core";
import { WochaAuthService } from "@wocha/angular";

@Component({ /* ... */ })
export class HeaderComponent implements OnInit {
  private auth = inject(WochaAuthService);

  user$ = this.auth.user$;
  isAuthenticated$ = this.auth.isAuthenticated$;

  ngOnInit() {
    this.auth.restore();
  }

  signIn() {
    this.auth.signIn();
  }

  signOut() {
    this.auth.signOut();
  }
}

Route protection

Use the functional wochaAuthGuard or class-based WochaAuthGuard on protected routes. Unauthenticated users are redirected to /login.

Security model

• Public client (PKCE): No client secret in the browser. Suitable for SPAs only.
• Token storage: Access and refresh tokens are stored in sessionStorage (cleared when the tab closes).
• No server-side session: Use @wocha/nextjs or @wocha/sveltekit for BFF patterns with httpOnly cookies.

Related packages

| Package | Use when | |---------|----------| | @wocha/vue | Vue 3 SPA with the same PKCE flow | | @wocha/react | React SPA with the same PKCE flow | | @wocha/nextjs | Next.js App Router with server-side sessions | | @wocha/sdk | Server-side user/org management via the Management API |

Troubleshooting

redirect_uri_mismatch

The redirectUri must exactly match a redirect URI registered in the Wocha Console.

CSRF / state_mismatch

Clear site storage for your origin and retry. Do not start a second login flow before the first completes.