# n8n-nodes-auth-service

> n8n community node to validate tokens against an Auth Service instance

Latest version **1.0.1** (published 2026-11-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install n8n-nodes-auth-service
pnpm add n8n-nodes-auth-service
yarn add n8n-nodes-auth-service
bun add n8n-nodes-auth-service
```

## 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 | 1.0.1 |
| Published | 2026-11-18 |
| First published | 2026-04-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 54.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 0 |
| Author | Shlomi Porush |
| Maintainers | shlomiporush |
| Keywords | n8n-community-node-package, n8n, auth, token, validate |

## Links

- npm: https://www.npmjs.com/package/n8n-nodes-auth-service
- Repository: https://github.com/ShlomiPorush/n8n-nodes-auth-service
- Homepage: https://github.com/ShlomiPorush/n8n-nodes-auth-service#readme
- Issues: https://github.com/ShlomiPorush/n8n-nodes-auth-service/issues
- npm.io page: https://npm.io/package/n8n-nodes-auth-service

## 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.0.1 (latest) — 2026-11-18
- 1.0.0 — 2026-06-17
- 0.5.1 — 2026-04-29
- 0.5.0 — 2026-04-29
- 0.4.9 — 2026-04-29
- 0.4.8 — 2026-04-29
- 0.4.6 — 2026-04-26
- 0.4.5 — 2026-04-26
- 0.4.4 — 2026-04-26
- 0.4.3 — 2026-04-26
- 0.4.2 — 2026-04-26
- 0.4.1 — 2026-04-26
- 0.4.0 — 2026-04-26
- 0.3.9 — 2026-04-26
- 0.3.8 — 2026-04-26
- … 13 more at https://npm.io/package/n8n-nodes-auth-service/versions

## README

# n8n-nodes-auth-service

Custom [n8n](https://n8n.io/) community nodes for integrating with [**Auth Service**](https://github.com/ShlomiPorush/auth-master) — a self-hosted token authentication and authorization service.

## What is Auth Service?

[Auth Service](https://github.com/ShlomiPorush/auth-master) is a self-hosted microservice that manages API tokens and authorization. It provides:

- **Token management** — create, edit, revoke tokens with granular per-zone permissions
- **Zone-based authorization** — define zones (e.g. `orders`, `billing`) with `read`/`write`/`delete`/`all` access levels
- **Fast validation** — validate tokens via a simple REST API (`POST /validate`)
- **Admin dashboard** — modern web UI with MFA protection
- **Docker deployment** — runs as a Docker container with Redis + SQLite/PostgreSQL

### Quick Setup

To install Auth Service, follow the [Quick Start](https://github.com/ShlomiPorush/auth-master#quick-start) in its repository. Its setup script creates a private `.env` file with new random secrets. The service does not start while a required secret is missing or has a published value.

For full documentation, see the [Auth Service repository](https://github.com/ShlomiPorush/auth-master).

---

## Nodes in this Package

| Node | Type | Description |
|---|---|---|
| **Auth Service** | Action | Full API access — validate tokens, manage zones & tokens |
| **Auth Webhook** | Trigger | Webhook with built-in token validation (replaces Webhook + IF) |

## Installation

### Community Nodes (Recommended)

1. Go to **Settings → Community Nodes** in your n8n instance
2. Click **Install a community node**
3. Enter `n8n-nodes-auth-service`
4. Click **Install**

### Manual Installation

```bash
cd ~/.n8n
npm install n8n-nodes-auth-service
# Restart n8n
```

## Credentials

Add an **Auth Service API** credential in n8n:

| Field | Description |
|---|---|
| **Base URL** | Your Auth Service address (e.g. `http://auth:8080`) |
| **API Key** | An API key from the Auth Service dashboard, or the `ADMIN_API_KEY` env var |

The credential is automatically tested on save by calling `GET /tokens/ping`.

---

## Auth Service Node

Full API access to your Auth Service instance.

### Operations

| Operation | Description | Required Scope |
|---|---|---|
| **Validate Token** | Check if a token is valid for a zone + permission level | _(public endpoint)_ |
| **List Zones** | Get all zones | `zones:read` |
| **Create Zone** | Create a new zone | `zones:write` |
| **List Tokens** | Get all tokens with their grants, status, and metadata | `tokens:read` |
| **Create Token** | Create a new token with zone/level grants | `tokens:write` |
| **Edit Token** | Update name, grants, active status, or expiration | `tokens:write` |
| **Delete Token** | Delete a token permanently | `tokens:write` |

### Example: Validate a token

```
Webhook → Auth Service (Validate Token) → IF (result == true) → Continue / Respond 403
```

**Output:**
```json
{ "result": true }
```

### Example: Automated setup

```
Trigger → Auth Service (Create Zone) → Auth Service (Create Token)
```

---

## Auth Webhook Node

A webhook trigger that **automatically validates tokens** before executing the workflow.

Instead of building this:
```
Webhook → Auth Service (Validate) → IF (result) → Continue
                                  → IF (!result) → Respond 403
```

Use a single node:
```
Auth Webhook → Continue (token already validated)
```

### Configuration

| Setting | Description |
|---|---|
| **HTTP Method** | GET, POST, PUT, PATCH, DELETE, HEAD |
| **Path** | The full URL path after `/webhook/` |
| **Auth Zone** | Zone to validate against (dynamic dropdown) |
| **Auth Level** | Read / Write / Delete / All |
| **Token Source** | Authorization Header (Bearer) or Custom Header |
| **Custom Header Name** | Header name when using Custom Header (e.g. `X-Auth-Token`) |
| **Respond** | Immediately / When Last Node Finishes |
| **Response Code** | HTTP status code to return on success (default: 200) |

### How it works

1. A request comes in to the webhook URL
2. The node extracts the token from the configured source (Authorization header or custom header)
3. The token is validated against Auth Service (`POST /validate` with the configured zone + level)
4. **Valid token** → workflow executes, next node receives `{ headers, params, query, body }`
5. **Invalid/missing token** → responds `403 Forbidden`, workflow does **NOT** execute

### File uploads

Files sent as `multipart/form-data` reach the workflow as binary data. Each file field becomes a binary property with the field's name, without leading or trailing spaces. A field with an empty name becomes `data`. When a field holds several files, the properties are named `<field>_0`, `<field>_1`, and so on. The form fields are in `body`. Other request bodies never produce binary data, so a `files` key in a JSON body is plain data.

Do not add the **Binary Data** option, or turn it off. When it is on, which is its value when you add it, n8n does not parse the request body, so the workflow receives an empty `body` and no files.

n8n saves each upload to a temporary file first. n8n 2.39 and later delete these files after each request. On older n8n versions they stay in the temporary directory.

### Example: calling the webhook

```bash
curl -X POST https://your-n8n.com/webhook/my-api \
  -H "Authorization: Bearer tok_abc123" \
  -H "Content-Type: application/json" \
  -d '{"order_id": 42}'
```

---

## API Key Scopes

API keys can be created in the Auth Service dashboard with granular scopes:

| Scope | Description |
|---|---|
| `validate` | Not required by any endpoint. `/validate` is public and needs no API key. |
| `tokens:read` | List tokens and zones |
| `tokens:write` | Create, edit, delete tokens |
| `zones:read` | List zones |
| `zones:write` | Create zones |

The `ADMIN_API_KEY` environment variable always has full access to all scopes.

## API Endpoints Used

| Endpoint | Method | Auth | Used By |
|---|---|---|---|
| `/tokens/ping` | `GET` | API Key | Credential test (no scope required) |
| `/tokens/zones` | `GET` | API Key | Auth Service (List Zones), Auth Webhook (zone dropdown) |
| `/tokens/zones` | `POST` | API Key | Auth Service (Create Zone) |
| `/tokens` | `GET` | API Key | Auth Service (List Tokens) |
| `/tokens` | `POST` | API Key | Auth Service (Create Token) |
| `/tokens/{id}` | `PATCH` | API Key | Auth Service (Edit Token) |
| `/tokens/{id}` | `DELETE` | API Key | Auth Service (Delete Token) |
| `/validate` | `POST` | None | Auth Service (Validate), Auth Webhook |

## License

MIT

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