bea-expert

n8n community node for beA.expert API (beA – besonderes elektronisches Anwaltspostfach)

Package Information

Released: 4 mo ago

Downloads: 5 weekly / 316 monthly

Latest Version: 1.0.1

Author: beA.expert Integration

Available Nodes

Documentation generating…

beA.expert

Interact with the beA.expert API for the German electronic lawyer mailbox (beA)

Documentation

n8n-nodes-bea-expert

beA.expert API connector for n8n — Automate the German besonderes elektronisches Anwaltspostfach (beA) from any n8n workflow.

What is this?
Architecture overview
Prerequisites
Provider setup (you)
Customer setup
Supported operations
Example workflows
Development
Contributing
License

What is this?

This repository provides a custom n8n community node that connects n8n workflows to the beA.expert API — an unofficial REST layer on top of the official German lawyer mailbox (beA).

With this node you can automate tasks like:

Polling the inbox for new legal messages
Downloading and archiving attachments
Sending beA messages from workflows
Moving, archiving, or categorising messages
Searching the national lawyer directory

Architecture overview

The beA.expert login process requires CMS signing (via OpenSSL CLI) and RSA-OAEP decryption of session keys. These operations need native system binaries and filesystem access, which are not available inside n8n's JavaScript sandbox.

The solution is a thin PHP proxy that lives on your server and handles the cryptographic handshake:

┌──────────────────────────────────────────────────────────────┐
│  Customer's n8n instance                                     │
│                                                              │
│  ┌─────────────────┐     ┌──────────────────────────────┐   │
│  │ HTTP Request    │     │ beA.expert node              │   │
│  │ (Login step)    │     │ (all other operations)       │   │
│  └────────┬────────┘     └──────────────┬───────────────┘   │
└───────────┼──────────────────────────────┼───────────────────┘
            │                              │
            ▼                              ▼
┌───────────────────────┐      ┌───────────────────────────┐
│  Your PHP Proxy       │      │  beA.expert API           │
│  (login_proxy.php)    │      │  (api.bea.expert)         │
│                       │      │                           │
│  - CMS signing        │      │  - Folder/message ops     │
│  - RSA key decrypt    │      │  - Address book           │
│  - Returns token +    │      │  - Identity/search        │
│    sessionKey         │      │                           │
└───────────────────────┘      └───────────────────────────┘

Login flow → goes through your proxy
Everything else → the n8n node calls the beA.expert API directly

Prerequisites

For the proxy server (provider)

Linux server with public HTTPS access
PHP 8.1 or higher
PHP extensions: openssl, curl, json
openssl CLI binary in $PATH
Apache or Nginx

For the n8n node (customer)

n8n self-hosted v1.0+ (community nodes are not available on n8n Cloud free tier)
Node.js 18+
A beA.expert account with a valid .p12 software token

Provider setup (you)

This section is for whoever hosts the integration — typically the software vendor deploying this for law firms.

Step 1 — Deploy the PHP proxy

Upload files to your PHP server (same directory):

/var/www/bea-proxy/
├── bex_api.php          ← the beA.expert library (from bea.expert)
├── Crypt/RSA.php        ← phpseclib dependency
└── login_proxy.php      ← from this repository (proxy/ folder)

Set the proxy secret (used to authenticate n8n requests to your proxy):

# Add to your server environment or .env file
export BEX_PROXY_SECRET="replace-with-a-long-random-string"

On Apache, add to your VirtualHost:

SetEnv BEX_PROXY_SECRET "replace-with-a-long-random-string"

Configure Nginx so that only the /login endpoint is publicly reachable:

server {
    listen 443 ssl http2;
    server_name bea-proxy.your-domain.com;
    root /var/www/bea-proxy;

    location = /login {
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root/login_proxy.php;
        fastcgi_param REQUEST_METHOD  $request_method;
        fastcgi_param CONTENT_TYPE   $content_type;
        fastcgi_param CONTENT_LENGTH  $content_length;
    }

    location / { return 404; }
}

Set BEX_PROXY_SECRET in your PHP-FPM pool config (/etc/php/8.1/fpm/pool.d/www.conf), not in Nginx — see the full tutorial for details.

Test the proxy:

# Base64-encode your test .p12 file
CERT_B64=$(base64 -w 0 /path/to/token.p12)

curl -s -X POST https://bea-proxy.your-domain.com/login \
  -H "Authorization: Bearer replace-with-a-long-random-string" \
  -H "Content-Type: application/json" \
  -d "{\"certB64\":\"$CERT_B64\",\"certPin\":\"YOUR_PIN\"}"

Expected response:

{
  "token": "eyJ...",
  "sessionKey": "abc123==",
  "safeId": "de.brak.bea...."
}

Step 2 — Build and publish the n8n node

# Clone this repository
git clone https://gitlab.com/your-group/n8n-nodes-bea-expert.git
cd n8n-nodes-bea-expert

# Install dependencies
npm install

# Build TypeScript → JavaScript
npm run build

# Option A: Publish to npm (public or private registry)
npm publish

# Option B: Pack as a .tgz for manual distribution
npm pack
# → produces n8n-nodes-bea-expert-1.0.0.tgz

Step 3 — Document your proxy URL for customers

Tell customers:

Your proxy URL: https://bea-proxy.your-domain.com/login
Their individual proxy secret (generate one per customer for security)
The beA.expert bex-ident value they need

Customer setup

This section is for law firms or end-users installing the node in their n8n instance.

Step 1 — Install the n8n node

Option A — From npm:

# SSH into your n8n server
cd ~/.n8n   # or your n8n data directory
npm install n8n-nodes-bea-expert
# Restart n8n

Option B — From .tgz (provided by your vendor):

cd ~/.n8n
npm install /path/to/n8n-nodes-bea-expert-1.0.0.tgz
# Restart n8n

Option C — n8n UI (if your instance allows it):
Settings → Community Nodes → Install → enter n8n-nodes-bea-expert

Step 2 — Convert your .p12 certificate to Base64

# On Linux / macOS
base64 -w 0 your-token.p12 > your-token.p12.b64
cat your-token.p12.b64

# On Windows PowerShell
[Convert]::ToBase64String([IO.File]::ReadAllBytes("C:\path\to\token.p12"))

Copy the resulting Base64 string — you will paste it into the n8n credential.

Step 3 — Create the credential in n8n

Open n8n → Credentials → Add Credential
Search for beA.expert API

Fill in the fields:

Field	Value
API URL	Provided by your vendor (e.g. `https://api.bea.expert/`)
BEX Ident	Your personal `bex-ident` identifier from your beA.expert account
P12 Certificate (Base64)	The Base64 string from Step 2
P12 PIN	The PIN for your .p12 certificate

Click Save

Step 4 — Build your first workflow

Every workflow starts with a Login step using an HTTP Request node, followed by any number of beA.expert nodes.

Login node (HTTP Request)

Setting	Value
Method	`POST`
URL	`https://bea-proxy.your-domain.com/login`
Authentication	Header Auth
Header name	`Authorization`
Header value	`Bearer <proxy-secret>`
Body	JSON
Body content	`{ "certB64": "PASTE_YOUR_P12_BASE64_HERE", "certPin": "YOUR_PIN" }`

Store certB64 and certPin in n8n Variables (Settings → Variables) and reference them as ={{ $vars.BEA_CERT_B64 }} to avoid hardcoding secrets in the workflow.

The response gives you:

{ "token": "...", "sessionKey": "...", "safeId": "..." }

Store these with Set node variables or use them directly in downstream nodes via expressions like {{ $('Login').item.json.token }}.

beA.expert node (example: read inbox)

Add a beA.expert node
Resource: Folder
Operation: Get Folder Overview
Session Token: {{ $('Login').item.json.token }}
Session Key: {{ $('Login').item.json.sessionKey }}
Folder ID: (your inbox folder ID — get it from Get Folder Structure first)

Supported operations

🔐 Session

Operation	Description
Check Session	Verify a session token is still alive

📬 Postbox

Operation	Description
Get Postboxes	List all postboxes for the logged-in user

✉️ Message

Operation	Description
Get Message	Fetch and decrypt a single message + attachments
Send Message	Compose and send an end-to-end encrypted beA message
Save Draft	Save a message as a draft
Move to Trash	Move a message to the trash folder
Restore from Trash	Restore a trashed message
Delete Message	Permanently delete a message
Move to Folder	Move a message to a specific folder

📁 Folder

Operation	Description
Get Folder Overview	List messages in a folder (subjects decrypted)
Get Folder Structure	Get the full folder tree of a postbox
Add Folder	Create a new sub-folder
Remove Folder	Delete a folder

📒 Address Book

Operation	Description
Get Address Book	Retrieve personal address book
Add Entry	Add a lawyer identity to the address book
Delete Entry	Remove an entry
Search	Search the national lawyer directory

👤 Identity

Operation	Description
Get Identity Data	Retrieve identity info for the current user
Get Username	Look up a username by SafeId
Get Message Config	Retrieve message defaults/configuration

🏛️ Court Codes

Operation	Description
Get Court Codes	List all German court codes (Gerichtscodes)

Example workflows

Poll inbox every 5 minutes

[Schedule Trigger: every 5 min]
        ↓
[HTTP Request: Login → proxy]
        ↓
[beA.expert: Get Postboxes]
        ↓
[beA.expert: Get Folder Structure → find inbox ID]
        ↓
[beA.expert: Get Folder Overview → list messages]
        ↓
[Split in Batches]
        ↓
[beA.expert: Get Message → decrypt + get attachments]
        ↓
[IF: attachment exists?]
    ↓ Yes                ↓ No
[Save to disk]     [Send email notification]
        ↓
[beA.expert: Move to Folder → "processed"]

Send a message on form submission

[Webhook Trigger]
        ↓
[HTTP Request: Login → proxy]
        ↓
[beA.expert: Search → find recipient SafeId by name]
        ↓
[beA.expert: Send Message]
        ↓
[Respond to Webhook: success]

Development

Project structure

n8n-nodes-bea-expert/
├── credentials/
│   └── BeaExpertApi.credentials.ts   # Credential definition
├── nodes/
│   └── BeaExpert/
│       └── BeaExpert.node.ts         # Main node logic
├── proxy/
│   └── login_proxy.php               # PHP login proxy
├── docs/
│   └── TUTORIAL.md                   # Step-by-step tutorial
├── index.ts                          # Package entry point
├── package.json
├── tsconfig.json
├── .eslintrc.js
├── .gitignore
├── CHANGELOG.md
├── CONTRIBUTING.md
└── LICENSE

Local development

git clone https://gitlab.com/your-group/n8n-nodes-bea-expert.git
cd n8n-nodes-bea-expert
npm install
npm run dev        # watch mode (auto-recompile on save)
npm run build      # production build
npm run lint       # check code style
npm run lintfix    # auto-fix code style issues

Link to a local n8n instance for testing

# In this repo
npm run build
npm link

# In your n8n data directory
npm link n8n-nodes-bea-expert

# Restart n8n — the node will appear in the palette

Contributing

Please read CONTRIBUTING.md before submitting merge requests.

Fork the repository
Create a feature branch: git checkout -b feature/my-new-operation
Commit your changes: git commit -m 'feat: add my-new-operation'
Push the branch: git push origin feature/my-new-operation
Open a Merge Request

License

MIT — see LICENSE.

The underlying beA.expert PHP library (bex_api.php) is licensed under GPL-2.0 and BSD-3-Clause by be next GmbH.

bea-expert

Package Information

Available Nodes

Documentation

n8n-nodes-bea-expert

Table of Contents

What is this?

Architecture overview

Prerequisites

For the proxy server (provider)

For the n8n node (customer)

Provider setup (you)

Step 1 — Deploy the PHP proxy

Step 2 — Build and publish the n8n node

Step 3 — Document your proxy URL for customers

Customer setup

Step 1 — Install the n8n node

Step 2 — Convert your .p12 certificate to Base64

Step 3 — Create the credential in n8n

Step 4 — Build your first workflow

Login node (HTTP Request)

beA.expert node (example: read inbox)

Supported operations

🔐 Session

📬 Postbox

✉️ Message

📁 Folder

📒 Address Book

👤 Identity

🏛️ Court Codes

Example workflows

Poll inbox every 5 minutes

Send a message on form submission

Development

Project structure

Local development

Link to a local n8n instance for testing

Contributing

License

Discussion

bea-expertInstall

Package Information

Available Nodes

Documentation

n8n-nodes-bea-expert

Table of Contents

What is this?

Architecture overview

Prerequisites

For the proxy server (provider)

For the n8n node (customer)

Provider setup (you)

Step 1 — Deploy the PHP proxy

Step 2 — Build and publish the n8n node

Step 3 — Document your proxy URL for customers

Customer setup

Step 1 — Install the n8n node

Step 2 — Convert your .p12 certificate to Base64

Step 3 — Create the credential in n8n

Step 4 — Build your first workflow

Login node (HTTP Request)

beA.expert node (example: read inbox)

Supported operations

🔐 Session

📬 Postbox

✉️ Message

📁 Folder

📒 Address Book

👤 Identity

🏛️ Court Codes

Example workflows

Poll inbox every 5 minutes

Send a message on form submission

Development

Project structure

Local development

Link to a local n8n instance for testing

Contributing

License

Discussion

bea-expert