When should I use the OAuth Application (Headless Server) client extension type?

• You are shipping a Batch extension that imports data via the Headless Batch Engine. • A Site Initializer needs to provision content, structures, and roles via API. • You need a Liferay-provisioned OAuth client without clicking through admin UI.

How do I create a OAuth Application (Headless Server) client extension?

1. Declare the extension with a stable identifier (used as the OAuth `externalReferenceCode`). 2. Grant the scopes you need (`Liferay.Headless.Admin.Site.everything`, etc.). 3. Reference this extension by name from a sibling `batch` or `siteInitializer` extension.

OAuth Application (Headless Server)

type: oAuthApplicationHeadlessServer·Configuration·Liferay docs →

at a glance

OAuth Application (Headless Server) (type: oAuthApplicationHeadlessServer) is a Liferay Client Extension in the Configuration category. Provisions an OAuth 2.0 client suitable for machine-to-machine (server-to-server) calls into Liferay's headless APIs — the client credentials grant flow. Paired with `batch` and `siteInitializer` extensions that need Liferay API access on deploy. Grant only the scopes your workload needs (each Liferay Headless API defines its own scope alias — `Liferay.Headless.Admin.User.everything`, `Liferay.Headless.Batch.Engine.everything`, etc.). Bind the OAuth app to a user account via `userAccountEmailAddress` or `userAccountScreenName`, otherwise it defaults to the deployment user — check your Liferay docs for scope guidance.

yaml type: oAuthApplicationHeadlessServer
category: Configuration
required fields: none (all optional)
liferay docs: learn.liferay.com →

# description

Provisions an OAuth 2.0 client suitable for machine-to-machine (server-to-server) calls into Liferay's headless APIs — the client credentials grant flow. Paired with `batch` and `siteInitializer` extensions that need Liferay API access on deploy. Grant only the scopes your workload needs (each Liferay Headless API defines its own scope alias — `Liferay.Headless.Admin.User.everything`, `Liferay.Headless.Batch.Engine.everything`, etc.). Bind the OAuth app to a user account via `userAccountEmailAddress` or `userAccountScreenName`, otherwise it defaults to the deployment user — check your Liferay docs for scope guidance.

# when to use

→You are shipping a Batch extension that imports data via the Headless Batch Engine.
→A Site Initializer needs to provision content, structures, and roles via API.
→You need a Liferay-provisioned OAuth client without clicking through admin UI.

# how to use

01Declare the extension with a stable identifier (used as the OAuth externalReferenceCode).
02Grant the scopes you need (Liferay.Headless.Admin.Site.everything, etc.).
03Reference this extension by name from a sibling batch or siteInitializer extension.

# optional fields

field	type	description
`name`	`string`	Application profile name.
`description`	`string`	Description.
`homePageURL`	`string`	Base URL. Defaults to the DXP main domain.
`privacyPolicyURL`	`string`	Privacy policy URL.
`scopes`	`string[]`	OAuth scopes granted to the app.
`userAccountEmailAddress`	`string`	Email of the user account bound to this OAuth app.
`userAccountScreenName`	`string`	Screen name (overrides email if both set).

# example

client-extension.yaml

my-oauth-headless:
    type: oAuthApplicationHeadlessServer
    name: Batch Loader
    scopes:
        - Liferay.Headless.Admin.User.everything
        - Liferay.Headless.Batch.Engine.everything

# more in configuration

cd ..scaffold this type in VS Code →