Chapter 06

Signing in

Your laptop is about to talk to a company server. That takes an address, an identity, a place to save, and a way to keep the secrets out of sight. Here is every value, in plain words.

Updated 5 Nov 2026Pega 24 – 26

Words you will meet

OAuth
authenticate

On this page7

01The hotel key card
02Every value, and where it comes from
03Build the config file
04Application, ruleset, version
05Keeping secrets secret
06The Deployment Hub’s file
07Sign in

The idea

A hotel key card.

A hotel does not let you walk into a room because you ask nicely. You prove who you are at the desk, and they hand you a key card that opens only your room, for only your stay. Pega works the same way, using a standard called OAuth.

Your tool is the guest. The client ID and secret are the reservation your administrator made for it. The token is the key card Pega hands back, and your tool shows it with every request. You never type a password into the build tool again until the card expires.

The reference

Every value, and where it comes from.

These live in a file in your project called tasks.config.json, inside a block named server-config. You will ask other people for some of these. This table says what to ask for.

Setting	What it is	Where you get it	Looks like
server	The address of your Pega server. It must start with https:// and end with /prweb/.	The address you use to open Pega in the browser, up to and including /prweb/. Or ask your administrator.	https://your-pega-server.example.com/prweb/
clientId	The ID of an OAuth client: the identity your tool signs in as.	An administrator creates the client in Pega (an OAuth 2.0 client registration) and gives you the ID.	<client id>
clientSecretsecret	That client’s password. Needed for the client-credentials and password-credentials sign-in styles.	Held by whoever created the client. Ask that administrator, and never ask for it in a public channel.	<client secret>
grantType	How the tool proves itself: authCode, clientCreds or passwordCreds.	Your choice, within what your client allows. Ask what yours is set up for.	clientCreds
redirectUri	Authorization code only. Where Pega sends your browser back after you sign in.	The tool’s default is https://localhost:4010/. It must match what the client has registered.	https://localhost:4010/
authService	Authorization code only. Which Pega sign-in service to use.	The default alias is pega. Ask your administrator if your server uses another.	pega
user, passwordsecret	Password credentials only. A real Pega operator’s login.	Your own operator account, or one provided for builds.	<pega user>, <pega password>
rulesetName	The Pega ruleset your component is saved into.	Choose one that belongs to your application. Ask your Pega lead.	AcmeComponents
rulesetVersion	Which version of that ruleset, written 00-00-00.	A version that exists in your application (see below).	01-01-01
authorizeUri	Optional (26.1+). Custom OAuth authorization endpoint if separated from the main server URL (e.g. Launchpad vanity URLs or enterprise SSO gateways).	Your Launchpad or SSO administrator.	https://auth.example.com/oauth/authorize
tokenUri	Optional (26.1+). Custom OAuth token exchange endpoint if separated from the main server URL.	Your Launchpad or SSO administrator.	https://auth.example.com/oauth/token

Play

Build the file. Break a value.

Fill in the address, ruleset and version, and choose a sign-in style. The two files on the right update, and each value is checked against the rules the tools enforce. Try an address without the final slash, or a ruleset with a hyphen.

Config file builderTry it: type a bad address, then fix it

Server address

The web address of your Pega server, ending in /prweb/.

Ruleset name

The folder in Pega your component is saved into.

Ruleset version

Which version of that folder.

How should the tool sign in? (grant type)

Authorization codeauthCodeClient credentialsclientCredsThe tool signs in as the client itself, with no person involved. Good for scripts.NeedsClient ID and client secret.Password credentialspasswordCreds

Development build (quicker, keeps source maps)Hub: read the secret from an environment variable

{
  "server-config": {
    "rulesetName": "AcmeComponents",
    "rulesetVersion": "01-01-01",
    "sourceOfComponents": "Server",
    "devBuild": true,
    "serverType": "infinity",
    "server": "https://your-pega-server.example.com/prweb/",
    "grantType": "clientCreds",
    "clientId": "<client id>",
    "clientSecret": "<client secret>"
  }
}

These values pass the same checks the tools run.

Anything in angle brackets is a placeholder you replace on your own machine. This page never asks for a real secret, and nothing you type leaves your browser.

The full tasks.config.json also holds a few housekeeping keys such as components-directory-path (src/components), sourceOfComponents, devServerPort, serverType (infinity for a Pega Infinity server) and a component.library name. The project ships a tasks.config.sample.json with all of them: copy it to start.

Terminal · start from the sample

cp tasks.config.sample.json tasks.config.json      # macOS / Linux / Git Bashcopy tasks.config.sample.json tasks.config.json    # Windows cmd or PowerShell

Where it lives

Application, ruleset, version.

Pega stores everything it knows as rules, and rules are kept in labelled folders called rulesets. A ruleset has versions, so changes can be tracked and rolled out in order. An application is the list of rulesets (and versions) that make up one piece of software.

When you publish, your component is saved as a rule inside the ruleset version you named. For Pega to use it, that ruleset version has to be part of the application that is running.

Applicationthe software being built, e.g. a case-management app
Ruleseta named folder of its rules, e.g. AcmeComponents
Versionone numbered release of that folder, e.g. 01-01-01
Your componentsaved as a rule inside that version

Important

Keeping secrets secret.

Files the project already tells Git to ignore include tasks.config.json, tasks.config-dev.json, .env*, hub.config.json, the hub's local sign-in files and the generated store/ folder. For the Deployment Hub there is a tidier option than writing a secret into a file at all:

hub.config.json · read the secret from the environment

"clientSecret": "env:PEGA_DEV_CLIENT_SECRET"# the hub reads PEGA_DEV_CLIENT_SECRET from your environment,# so the secret never sits in the file

The second file

The Deployment Hub's own file.

Typing publish commands gets old. The project includes the Deployment Hub: start it with npm run hub and it opens at http://localhost:3050/hub. It reads its servers from a second file, hub.config.json, which you copy from hub.config.sample.json.

Key	Needed?	What it does
servers	required	The servers you publish to. At least one.
name	recommended	What the hub calls this server in its list.
url	required	Starts with https:// and ends with /prweb/.
clientId	recommended	This server’s own OAuth client. With it, the hub signs in by itself.
clientSecret	recommended	Its secret. Write env:NAME to read it from an environment variable instead of keeping it in the file.
connection	optional	A sign-in saved in the hub’s Connections tab, used when the server has no clientId.
build	optional	dev (quicker, keeps source maps) or production. Left out means dev.
rulesets[].name	required	Letters, numbers, underscores. Starts with a letter. Up to 64 characters.
rulesets[].versions	required	A list such as ["01-01-01", "01-02-01"].
rulesets[].build	optional	Overrides the server’s build for this ruleset.

Keys that start with an underscore are treated as notes and ignored. Save the file while the hub is running and its Server, Ruleset and Version dropdowns refresh by themselves.

Sign in.

Terminal

npm run authenticate

The tool asks for what it does not already know (server, sign-in style, client details) and saves your answers back into tasks.config.json. Settings listed under questions_askOnce are asked the first time and remembered. With the authorization-code style, a browser window opens for you to sign in. The token it receives is kept locally, inside the builder's folder in node_modules.

If it fails, check three things in order: the server address (ends in /prweb/), the client ID and secret, and that the sign-in style you chose is one your client allows. Chapter 13 has a full troubleshooting table.

Your turn

Questions and comments

Stuck on something, or have a thought? Write it here. To talk about one part, use the Comment button under that section's heading.