Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared hosting Managed WordPress Cloud hosting VPS hosting By reader location Hosting finder
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Blog Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Developer · Guide

How to Build a Headless WordPress Site

How to Build a Headless WordPress Site

Short answer

To build a headless WordPress site, keep WordPress as the content back end and build a separate front end that reads content through the REST API at /wp-json/. Fetch posts from /wp/v2/posts as JSON, authenticate writes with an Application Password over HTTPS, and render pages from the data your front end receives.

Key takeaways

  • Headless WordPress keeps the editor and uses a separate front end to show content.
  • The REST API lives at /wp-json/, with core routes under the wp/v2 namespace.
  • Public reads need no credentials, but writes and drafts need auth.
  • Application Passwords are 24-character credentials, shown once and revocable.
  • Basic Auth must run over HTTPS, since the credentials travel as cleartext.
  • Check the API index first when a route returns an error.

What is a headless WordPress site?

A headless WordPress site keeps WordPress as the content back end and uses a separate front end, such as a JavaScript app, to show the content.

In a headless setup, editors still write in WordPress, and visitors never see the WordPress theme. The front end asks WordPress for content through the REST API and renders the pages itself.

The REST API Handbook describes the API as the way to match URIs to resources in a WordPress install, and the front end uses those matches to pull posts, pages, media, and more. Routes and Endpoints covers how routes and endpoints work (checked November 2026).

A guide on headless WordPress vs traditional WordPress compares the two shapes in more depth, so read it before you pick one.

What do you need before you build a headless site?

You need a WordPress site with pretty permalinks, HTTPS, a front-end host, and a plan for authentication before you build.

Pretty permalinks put the API at /wp-json/. The REST API Handbook states that by default, if you have pretty permalinks enabled, the WordPress REST API lives at /wp-json/. Routes and Endpoints states that base path (checked November 2026).

HTTPS is required for safe authentication. The Application Passwords handbook states that because Basic Auth credentials can be intercepted on the network if sent unencrypted, you should always use HTTPS. Application Passwords states that rule (checked November 2026).

Pick the front-end host and the framework before you write code. Common choices are a static host for a site that rebuilds when content changes, or a Node host for pages that render on each request. The API does not care which one you pick.

Plan authentication early. Public reads need no credentials, but drafts, private posts, and all writes need a logged-in user or a token. Decide which account the front end will use, and give that account the smallest role that can do the job.

How does the WordPress REST API work?

The WordPress REST API is a JSON interface built into core that lets other software read and write your content over HTTP.

The API index lists what a site exposes. The REST API Handbook states that a GET request to https://ourawesomesite.com/wp-json/ returns the index, with the routes, the HTTP methods, and the endpoints registered for that install. Routes and Endpoints states that (checked November 2026).

A route is the name you use to reach an endpoint, and an endpoint is the function behind it for one HTTP method.

The handbook states that a route can have multiple endpoints linked to it, and which one runs depends on the HTTP verb. Routes and Endpoints states that distinction (checked November 2026).

The handbook gives one URL with three endpoints as its example: http://example.com/wp-json/wp/v2/posts/123.

A GET request triggers the get_item method and returns the post, a PUT request triggers update_item, and a DELETE request triggers delete_item. Routes and Endpoints gives that example (checked November 2026).

Core routes live under the wp/v2 namespace. The handbook states that namespaces matter, and that you should not place anything into the wp namespace unless you plan to merge it into core. Routes and Endpoints states that rule (checked November 2026).

On sites without pretty permalinks, the route goes in the URL as the rest_route parameter, such as http://example.com/?rest_route=/wp/v2/posts/123. Routes and Endpoints states that fallback (checked November 2026).

RouteWhat it returnsAuth needed?
/wp-json/The API index with all routesNo
/wp/v2/postsPublished postsNo for reading
/wp/v2/posts/123One post by IDNo for reading
/wp/v2/pagesPublished pagesNo for reading
/wp/v2/mediaMedia itemsNo for reading
/wp/v2/categoriesCategoriesNo for reading
/wp/v2/searchSearch resultsNo for reading
/wp/v2/users/meThe current userYes

How do you fetch posts and pages from the API?

Send a GET request to a route such as /wp-json/wp/v2/posts, and WordPress returns the matching posts as JSON.

Start by opening the index in a browser: https://example.com/wp-json/ with your own domain in place of example.com. If it returns a JSON document that lists routes, the API is answering. If it returns a 404, pretty permalinks may be off or the server rewrites may be broken.

Then fetch the posts collection with a plain request:

curl https://example.com/wp-json/wp/v2/posts

The response is a JSON array of post objects, each with an ID, a title, content, a link, and related data. Your front end reads the fields it needs and renders them into HTML.

In JavaScript, the same request looks like this:

fetch( 'https://example.com/wp-json/wp/v2/posts?per_page=5' )
  .then( function( response ) { return response.json(); } )
  .then( function( posts ) { console.log( posts ); } );

Add query parts to shape the result, such as per_page for the count and search for a keyword.

Use the _fields parameter to ask for a smaller set of fields, since the handbook states that you should use _fields or contexts instead of changing the response. Modifying Responses states that guidance (checked November 2026).

Custom post types and custom fields need two extra steps: the post type must be visible in the API, and each meta field must be registered with show_in_rest set to true.

The REST API Handbook states that such a field will be exposed on a .meta key in the endpoint response. Modifying Responses states that (checked November 2026).

If the API itself returns an error, a guide on fixing the REST API error in Site Health walks through the checks that confirm the API is answering.

How do you authenticate API requests?

Read public content with no credentials, and authenticate writes and private content with an Application Password or a token.

Application Passwords are the built-in choice. They were introduced in WordPress 5.6 in December 2020. Application Passwords states that date (checked November 2026).

An Application Password is tied to one user account, is shown only once at creation, and can be revoked on its own without changing the user main password. Application Passwords lists those traits (checked November 2026).

Each password is 24 characters long, made only of upper-case letters, lower-case letters, and numbers.

The Make WordPress integration guide states that the format comes to over 142 bits of entropy, and that the password is shown in chunks such as abcd EFGH 1234 ijkl MNOP 6789. Application Passwords: Integration Guide gives those facts (checked November 2026).

Create one from Users, then Profile, in the Application Passwords section. Type a name for the app, generate the password, and copy it at once, since it will not be shown again. Application Passwords gives those five steps (checked November 2026).

Send it with HTTP Basic Authentication, which encodes a user-id and password pair in Base64. The IETF standard states that the Basic scheme transmits credentials as user-id and password pairs, encoded using Base64. RFC 7617 defines that scheme (checked November 2026).

The same standard warns that the scheme is not a secure method of user authentication unless used with an external secure system such as TLS, since the user-id and password are passed over the network as cleartext. RFC 7617 states that warning (checked November 2026).

A request with curl looks like this:

curl --user "USERNAME:APPLICATION_PASSWORD" https://example.com/wp-json/wp/v2/users/me

Application Passwords cannot be used to log into wp-admin through wp-login.php. Application Passwords states that limit (checked November 2026).

For token-based auth, a JWT plugin is the common route. The Simple JWT Auth plugin registers an auth/v1 namespace with five endpoints: token, token refresh, token revoke, token validate, and me. Simple JWT Auth lists those five endpoints (checked November 2026).

The same plugin page states that access tokens last 900 seconds by default and refresh tokens last 1,209,600 seconds, and that the plugin requires PHP 8.2 or newer and WordPress 7.0 or newer. Simple JWT Auth gives those numbers (checked November 2026).

Track use after you create a credential. The integration guide states that once a password has been used, WordPress keeps track of where and when it was used, and that the Last Used column is accurate to within 24 hours. Application Passwords: Integration Guide states that (checked November 2026).

How do you build the front end?

Build the front end as a JavaScript app that fetches JSON from the API at build time or on each request, then renders pages from it.

At build time, the app fetches every post and page once, renders static HTML, and ships that HTML to a static host. Content changes need a rebuild, so this shape fits sites that publish a few times a day.

On each request, the app fetches from the API when a visitor loads a page. Content is always fresh, but each visit costs one or more API calls, so this shape needs caching to stay fast.

The API does not force a framework. The Simple JWT Auth plugin page notes that its auth works from React, Next.js, Vue, mobile apps, and any other external client. Simple JWT Auth lists those clients (checked November 2026).

For GraphQL instead of REST, the integration guide notes that with a small code addition, WPGraphQL can accept authenticated requests using only the Application Passwords feature in core. Application Passwords: Integration Guide states that (checked November 2026).

Keep secrets out of the browser. A token that can write must live on your server or in a build step, never in JavaScript that ships to visitors. A guide on the WordPress Abilities API covers another API surface that front ends can call.

How do you handle previews, search, and forms?

Previews, search, and forms each need their own setup, since the front end no longer runs inside WordPress.

For previews, the front end must fetch the draft through the API with an authenticated request, since drafts are not public. Use a low-privilege account for preview links.

For search, use the /wp/v2/search route for a simple keyword search across content types.

For forms, send the submission to the API or to a form endpoint, not to a WordPress theme file. A form plugin with a REST route can accept the post, or your own small endpoint can take it.

To add your own route, the handbook states that you register it with register_rest_route(), called in a callback on rest_api_init, passing a namespace, a route, and the options. Routes and Endpoints states that pattern (checked November 2026).

Namespaces should follow the vendor/v1 pattern, with your plugin or theme slug as the vendor and a version number after it. The handbook states that namespaces should follow that pattern to stop routes from clashing. Routes and Endpoints states that rule (checked November 2026).

How do you check the headless site and fix common errors?

Open the API index in a browser, check the response codes, and confirm each route returns the data your front end needs.

First, open https://example.com/wp-json/ with your domain. A JSON index means the API is live. A 404 points to permalinks or server rewrites, and a 401 on a public route points to a plugin or a security rule that blocks the API.

Next, fetch one post and one page with curl, and confirm the JSON has the fields your templates use. If a field is missing, check that the meta field is registered with show_in_rest set to true.

For auth errors, check the credential first.

The Application Passwords handbook lists the checks: confirm HTTPS, confirm you are using an Application Password and not the user main password, confirm the feature is not disabled by a plugin, and confirm the client sends the Basic Auth header. Application Passwords lists those four checks (checked November 2026).

For the authorization flow, the integration guide states that you can check the authentication key in the API root response, and that if it holds an application-passwords object, it offers a URL to send a user to finish the flow. Application Passwords: Integration Guide states that (checked November 2026).

What mistakes should you avoid?

Avoid exposing admin credentials in front-end code, skipping HTTPS, and caching API responses without a plan to clear them.

Never put an Application Password or a token in JavaScript that ships to visitors. Anyone who reads it can act as that user. Keep write credentials on the server, and use a read-only path for public content.

Never run auth over plain HTTP. The Application Passwords handbook states that the feature is available by default when requests are served over HTTPS. Application Passwords states that (checked November 2026).

Do not cache a post list forever. A cached list will keep showing a deleted post until the cache clears, so tie the cache lifetime to your publish flow or clear it on each publish.

Do not guess routes from another site. The handbook states that the index gives the routes for that exact install, and plugins can add or remove routes. Check the index on your own site before you hard-code a path.

Frequently asked questions

Do editors still use WordPress in a headless setup?

Yes. WordPress stays as the editor and the content store, and the front end only reads from it. Editors keep the same dashboard, the same blocks, and the same media library, while visitors see pages rendered by the separate front end.

Do I need to log in to read posts from the API?

No. Reading published posts, pages, media, and categories needs no credentials. You only need to authenticate for drafts, private posts, settings, and any write request, such as creating a post or uploading media.

What is the best way to authenticate a headless front end?

Use an Application Password for a low-privilege user, sent with HTTP Basic Auth over HTTPS. For token-based auth, a JWT plugin can issue short-lived access tokens with a refresh token. Never put a write credential in front-end code that ships to visitors.

How do previews work when the front end is separate?

Drafts are not public, so the front end must fetch them with an authenticated request. Use a low-privilege account for preview links, and build a preview route that checks the credential before it renders the draft content.

How do I keep API responses small and fast?

Add _fields to the request to ask for a smaller set of fields, and use the context parameter to pick the view, embed, or edit shape. Keep responses small, cache them where you can, and fetch only the fields each page renders.

How do I check that the REST API is working?

Open yoursite.com/wp-json/ in a browser. A JSON index means the API is live. A 404 points to permalinks or server rewrites, and a 401 on a public route points to a plugin or a security rule that blocks the API.

Sources

  1. Routes and Endpoints WordPress Developer Resources
  2. Application Passwords WordPress Developer Resources
  3. Application Passwords: Integration Guide Make WordPress Core
  4. Modifying Responses WordPress Developer Resources
  5. RFC 7617: The 'Basic' HTTP Authentication Scheme IETF
  6. Simple JWT Auth WordPress.org

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

WPLegible editors

Researched from the primary sources listed above and checked against our editorial rules. About the site · How we test