REST API: Authentication & Usage

PolyCMS offers a comprehensive RESTful API out of the box, allowing you to build Headless frontends, mobile applications, or integrate with third-party tools (like Zapier, CRMs, or ERP systems).

The API is located at the /api/v1 prefix.

Authentication System

PolyCMS utilizes Laravel Sanctum to manage API authentication. It supports two primary methods depending on your use case:

SPA Authentication (Cookies): Used by the built-in Vue 3 Admin Panel. It relies on session cookies and CSRF protection.

API Token Authentication: Used for external applications, mobile apps, and "Sandbox Remote" modules. This method uses Bearer tokens.

This guide focuses on API Token Authentication for external integrations.

Generating a Personal Access Token (PAT)

To access protected endpoints, you must generate a token.

Log in to the PolyCMS Admin Panel.

Navigate to Settings > API Tokens (or click on your User Profile).

Click Create New Token.

Give the token a recognizable name (e.g., "Mobile App" or "Zapier Integration").

Crucial Step: You will only be shown the plain-text token once. Copy it immediately and store it in a secure password manager.

Making API Requests

Once you have your token, you must include it in the Authorization header of every HTTP request you make to the PolyCMS API.

Example: Fetching the Current User (cURL)

curl -X GET https://polycms.org/api/v1/user \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_PLAIN_TEXT_TOKEN_HERE"

Example: Creating a Post (JavaScript/Fetch)

const response = await fetch('https://polycms.org/api/v1/posts', {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_PLAIN_TEXT_TOKEN_HERE'
  },
  body: JSON.stringify({
    title: 'Hello via API',
    slug: 'hello-via-api',
    content_raw: '{"blocks":[{"type":"paragraph","data":{"text":"Created via REST!"}}]}',
    status: 'draft'
  })
});

const data = await response.json();
console.log(data);

Security Best Practices

HTTPS Only: Always make API requests over a secure https:// connection. Sending Bearer tokens over HTTP exposes your system to interception.

Token Revocation: If you suspect a token has been compromised, immediately revoke it in the Admin Panel under Settings > API Tokens.

Permissions: Currently, PATs inherit the exact permissions of the user who created them. Ensure you generate tokens using an account that only has the privileges necessary for the task (e.g., don't use an Administrator account for a read-only integration).