How Pottr Works

Pottr bridges the gap between client-friendly WordPress management and modern frontend engineering.

The End-to-End Workflow

1. Install Pottr in WordPress: Activate the plugin in any standard WordPress 6.0+ installation.
2. Define Your Application Data: Create collections visually in the WordPress Admin or declare them in code using a Blueprint JSON document.
3. Public REST API Exposure: Pottr immediately exposes structured JSON endpoints at /wp-json/pottr/v1/collections/{slug} with automatic filtering, sorting, and pagination.
4. Connect Your Frontend: Use your Public Key (pk_live_...) in your React, Next.js, Vue, or mobile frontend to read and write collection entries.
5. Add Application Capabilities: Enable decoupled app-user authentication (JWTs), turn on row-level security for user-owned records, configure webhooks, or automate deployments.

WordPress vs. Pottr Responsibilities

Installation & Requirements

System prerequisites, server checklist, and activation steps for running Pottr on WordPress.

Verified System Requirements

Installation Steps

1. Upload the pottr plugin folder to your WordPress installation's /wp-content/plugins/ directory (or install via the WordPress Plugins screen).
2. Navigate to Plugins → Installed Plugins in WordPress Admin and click Activate under Pottr.
3. Upon activation, Pottr registers the /wp-json/pottr/v1/ API namespace and provisions necessary schema tables.
4. Navigate to the new Pottr menu item in the WordPress admin sidebar to view the dashboard and copy your API Keys.

Quickstart Guide

Connect a frontend application to Pottr, declare your schema, and make your first verified API request in 5 minutes.

1. Retrieve Your API Keys

In the WordPress Admin, navigate to Pottr → API Keys. Copy your Public Key (starts with pk_live_).

2. Configure Environment Variables

In your frontend project (e.g. Next.js, Vite, React, Vue), configure your environment variables:

NEXT_PUBLIC_POTTR_API_URL="https://example.com/wp-json/pottr/v1"
NEXT_PUBLIC_POTTR_PUBLIC_KEY="pk_live_your_public_key_here"

3. Declare Schema via Bootstrap (Optional)

You can create collections in the WordPress Admin, or send a declarative bootstrap request using your Public Key when your app boots:

const response = await fetch('https://example.com/wp-json/pottr/v1/auth/bootstrap', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.NEXT_PUBLIC_POTTR_PUBLIC_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    app: 'task-manager',
    version: '1.0.0',
    collections: [
      {
        slug: 'tasks',
        name: 'Tasks',
        fields: [
          { key: 'title', type: 'text', required: true },
          { key: 'priority', type: 'text' },
          { key: 'completed', type: 'boolean' }
        ]
      }
    ]
  })
});

const result = await response.json();
console.log(result); // { status: "provisioned", ... }

4. Create and Query Entries

Create a task entry via POST /collections/tasks:

const createRes = await fetch('https://example.com/wp-json/pottr/v1/collections/tasks', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.NEXT_PUBLIC_POTTR_PUBLIC_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Ship documentation',
    priority: 'high',
    completed: false
  })
});

const newEntry = await createRes.json();
console.log(newEntry);

Fetch the list of tasks with pagination:

const res = await fetch('https://example.com/wp-json/pottr/v1/collections/tasks?limit=10&order_by=created_at&order=DESC', {
  headers: {
    'Authorization': `Bearer ${process.env.NEXT_PUBLIC_POTTR_PUBLIC_KEY}`
  }
});

const { data, meta } = await res.json();
console.log(data); // Array of entries
console.log(meta); // { total: 1, limit: 10, offset: 0, has_more: false }

Collections & Fields

How Pottr models structured application entities using 9 field types, strict validation, and normalized schemas.

What is a Collection?

In Pottr, a Collection represents a structured data entity — such as projects, tickets, invoices, or bookings. Unlike WordPress posts, collections do not use wp_posts or wp_postmeta, keeping your application data separated from editorial content.

Collection slugs must use lowercase alphanumeric characters with hyphens or underscores (matching ^[a-z][a-z0-9_-]*$).

The 9 Supported Field Types

The Primary Title Field

Every collection in Pottr includes a primary title field (type text, required). If you declare a collection via Blueprints without a title field, Pottr automatically prepends it to the schema.

Field Validation Rules

Field schemas support optional validation constraints enforced on POST, PUT, and PATCH:

• required (boolean): Rejects empty or missing values.
• min_length / max_length (integers): String length bounds on text and textarea.
• pattern (string): Regex pattern for custom format validation (e.g. ^[A-Z0-9]{6}$).
• min / max (numbers): Numerical range constraints on number fields.
• options (array of strings): Enum list of allowed values for dropdown/select fields.

Relationships & Expansion

Connecting entities across collections and resolving linked records with single-level relation expansion.

Declaring a Relation Field

To link one collection to another, declare a field with type: "relation" and specify the target_collection slug. By convention, relation field keys should use the _id suffix (e.g. project_id, author_id).

{
  "key": "project_id",
  "name": "Project",
  "type": "relation",
  "target_collection": "project",
  "required": true
}

Relation Expansion (?expand)

By default, querying a collection returns the numeric ID stored in the relation field. When your frontend needs the related data, append ?expand=field_key to inline the full related entry in a single HTTP request:

{
  "data": [
    {
      "id": 42,
      "title": "Write integration tests",
      "project_id": {
        "id": 7,
        "collection": "project",
        "data": {
          "title": "Q3 Mobile App Launch",
          "status": "in_progress"
        },
        "created_at": "2026-05-01 10:00:00",
        "updated_at": "2026-05-03 14:22:00"
      }
    }
  ],
  "meta": { "total": 1, "limit": 20, "offset": 0, "has_more": false }
}

User-Owned Data & Row-Level Security

Automatic data isolation and row-level privacy for multi-tenant portals, user dashboards, and private application stores.

How User-Ownership Works

Any collection containing a field named user_id (type relation or number) is automatically designated as user-owned. Pottr enforces strict row-level security without requiring custom permissions code:

• Read Scoping: GET /collections/{slug} queries automatically filter to only return entries owned by the authenticated app user (identified by their JWT). Unauthenticated requests return an empty list [].
• Server-Side ID Injection: When an authenticated user creates an entry (POST /collections/{slug}), Pottr extracts the user's ID from their verified JWT and attaches it server-side. Clients should omit user_id from the request body.
• Modification & Deletion Protection: When updating (PUT/PATCH) or deleting (DELETE), Pottr verifies that the target entry's user_id matches the authenticated user. Attempts to alter another user's entry return 403 forbidden.
• Administrative Access: Requests authenticated with the Secret Key (sk_live_...) or an active WordPress Administrator session bypass ownership checks, allowing backends and administrators to manage entries across all users.

Example: Creating a User-Owned Entry

// Notice: 'user_id' is NOT included in the body — it is injected server-side from the JWT
const res = await fetch('https://example.com/wp-json/pottr/v1/collections/notes', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.NEXT_PUBLIC_POTTR_PUBLIC_KEY}`,
    'X-Pottr-User-Token': userAccessToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'My Private Financial Goal',
    content: 'Confidential user data'
  })
});

API Overview & Conventions

Base URLs, authentication headers, payload conventions, response structures, and standard error handling.

Base Endpoint

All Pottr REST routes are anchored under the following base URL:

Authentication Header Model

Pottr supports three primary authentication patterns depending on your client environment:

Standard Error Response Format

When an error occurs, Pottr returns a normalized JSON error payload accompanied by the relevant HTTP status code:

{
  "error": true,
  "code": "invalid_api_key",
  "message": "The provided API key is invalid or revoked."
}

Common Error Codes

Working with Data (CRUD)

Full reference for creating, reading, updating, partially patching, and soft-deleting entries.

1. List Entries

Returns a paginated array of entries matching the collection schema.

{
  "data": [
    {
      "id": 1,
      "title": "First Task",
      "priority": "high",
      "completed": false,
      "created_at": "2026-05-01 12:00:00",
      "updated_at": "2026-05-01 12:00:00"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

2. Create Entry

Creates a new entry. Validates submitted fields against schema rules. Returns 201 Created.

{
  "title": "Deploy staging build",
  "priority": "urgent",
  "completed": false
}

3. Get Single Entry

Retrieves a single entry by its integer ID.

4. Replace Entry (PUT)

Replaces the full entry record. All required schema fields must be present and will be re-validated. Omitted optional fields are reset to their default empty values.

5. Partial Update (PATCH)

Partially updates an entry. Only the submitted fields are validated and updated; omitted fields retain their existing values.

// Mark a task as completed without sending other fields:
await fetch('https://example.com/wp-json/pottr/v1/collections/tasks/42', {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ completed: true })
});

6. Delete Entry (Soft-Delete)

Soft-deletes the entry. The entry immediately becomes invisible to all REST API queries. Soft-deleted records can be viewed or restored in the WordPress Admin.

{
  "success": true,
  "id": 42
}

Querying, Filtering & Sorting

Pagination parameters, sorting directives, field equality filters, and batch ID retrieval.

Query Parameters Reference

Filtering Examples

Multiple filters combine automatically with boolean AND:

# Filter active projects, sorted by updated date, page 2:
curl -H "Authorization: Bearer pk_live_..." \
  "https://example.com/wp-json/pottr/v1/collections/project?filter\[status\]=active&filter\[category\]=design&order_by=updated_at&order=DESC&limit=10&offset=10"

Batch ID Lookups

To fetch specific entries without manual iterative loops, pass ?ids=101,102,105. Batch queries maintain full row-level security for user-owned collections.

API Keys & Gateway Scopes

Understanding the Public Key vs Secret Key security model and endpoint permission gates.

Key Types & Prefixes

Key Regeneration

If a secret key is compromised, navigate to Pottr → API Keys in WordPress Admin and click Regenerate. Regenerating a key immediately invalidates the previous key across all active API requests.

App-User Authentication

Decoupled end-user authentication, JWT lifecycles, profile management, and password reset flows.

How are App Users Different from WordPress Admins?

Pottr provides an independent authentication layer designed specifically for end-users of your custom application:

• No WordPress Admin Access: App users cannot log into /wp-admin and have no core WordPress capabilities.
• No wp_users Bloat: App users are stored in dedicated application authentication tables, keeping WordPress administration clean.
• Custom Profile Fields: Blueprints allow declaring custom fields on user accounts (e.g. full_name, company, avatar_url).
• Stateless JWT Tokens: Authenticated via 15-minute HS256 JWT access tokens and 30-day hashed refresh tokens.

App Header Requirement (X-Pottr-App)

Every authentication endpoint requires an application identifier passed in the X-Pottr-App: <app_slug> request header (or an app string in the JSON body).

Authentication Endpoints

1. User Signup

Registers a new app user. Password must be at least 8 characters. Returns 201 Created with tokens.

const res = await fetch('https://example.com/wp-json/pottr/v1/auth/signup', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${PUBLIC_KEY}`,
    'X-Pottr-App': 'task-manager',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'alex@example.com',
    password: 'securePassword123',
    full_name: 'Alex Smith'
  })
});

2. User Login

Authenticates user credentials. Returns JWT access token (valid 15 minutes) and refresh token (valid 30 days).

3. Current User Profile

4. Token Refresh

Exchanges a valid 30-day refresh token for a fresh 15-minute access token.

{
  "refresh_token": "64_character_hex_refresh_token"
}

5. Logout

Deletes the submitted refresh token and increments the user's internal token version, immediately invalidating all outstanding JWT access tokens.

Password Reset Flow

1. Request Reset Email (POST /auth/forgot-password): Client submits { "email": "user@example.com" }. Pottr generates a secure 1-hour single-use transient token and sends a reset email via WordPress wp_mail(). Always returns 200 { success: true } to prevent email enumeration.
2. Complete Password Reset (POST /auth/reset-password): Client submits { "email": "...", "token": "...", "password": "newPassword" }. Pottr validates the token, updates the password hash, immediately destroys the token, and revokes active sessions.

Blueprints & Provisioning

Declarative schema definitions for automated, non-destructive application provisioning on boot or deploy.

What are Blueprints?

A Blueprint is a JSON document declaring your application's required collections, fields, and user authentication profile schema. When submitted to Pottr, the engine provisions missing collections and adds new fields automatically.

Additive, Non-Destructive Provisioning

Pottr provisioning is strictly additive:

• Existing collections and entries are never dropped or deleted.
• Existing fields retain their data.
• Any field defined in the blueprint that does not yet exist is safely added to the schema.
• The required primary title text field is automatically prepended if omitted.

Public vs Secret Provisioning Endpoints

Blueprint JSON Specification

{
  "app": "task-manager",
  "version": "1.0.0",
  "auth": {
    "slug": "users",
    "name": "App Users",
    "fields": [
      { "key": "full_name", "type": "text", "required": true },
      { "key": "avatar_url", "type": "text" }
    ]
  },
  "collections": [
    {
      "slug": "project",
      "name": "Projects",
      "fields": [
        { "key": "title", "type": "text", "required": true },
        { "key": "user_id", "type": "relation" }
      ]
    },
    {
      "slug": "task",
      "name": "Tasks",
      "fields": [
        { "key": "title", "type": "text", "required": true },
        { "key": "project_id", "type": "relation", "target_collection": "project" },
        { "key": "completed", "type": "boolean" }
      ]
    }
  ]
}

Webhooks & Event Notifications

Subscribing to collection data changes with HMAC-SHA256 signature verification.

Supported Events

• entry.created: Triggered when a new entry is created via POST.
• entry.updated: Triggered when an entry is updated via PUT or PATCH.
• entry.deleted: Triggered when an entry is soft-deleted via DELETE.
• *: Wildcard event triggering on all three operations.

Managing Webhooks

Webhooks are managed via REST routes requiring the Secret Key (sk_live_...):

Webhook Payload Structure

{
  "event": "entry.created",
  "timestamp": 1714999999,
  "payload": {
    "collection": "tasks",
    "entry": {
      "id": "42",
      "title": "Deploy update",
      "created_at": "2026-05-06 12:00:00"
    }
  }
}

Signature Verification (HMAC-SHA256)

Every delivery includes an X-Pottr-Signature header containing sha256=<hex_hash>. Compute the HMAC using the raw request body and your webhook secret:

const crypto = require('crypto');

function verifyPottrWebhook(rawBodyBuffer, signatureHeader, secret) {
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBodyBuffer)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expectedSignature)
  );
}

Security & Delivery Rules

• HTTPS Destination Required: Webhook URLs must use https://.
• SSRF Protections: Localhost, loopback IPs (127.0.0.1), private subnets (10.0.0.0/8, 192.168.0.0/16), and raw IP addresses are rejected.
• Synchronous Timeout: Deliveries execute with a 5-second timeout. Target endpoints should acknowledge delivery with 200 OK immediately.

Configuration & Directives

wp-config.php constants for CORS origins, local development, email URLs, and trusted reverse proxies.

Available wp-config.php Constants

Configuration Example

// 1. Allow production frontend origins
define( 'POTTR_ALLOWED_ORIGINS', 'https://app.example.com,https://staging.example.com' );

// 2. Frontend URL for password reset email links
define( 'POTTR_APP_URL', 'https://app.example.com' );

// 3. Trust reverse proxy (e.g. Cloudflare / Nginx) for accurate IP rate limiting
define( 'POTTR_TRUSTED_PROXIES', '10.0.0.1,10.0.0.2' );