Planning Center supports two kinds of credentials, and this library adds a third option for when
you manage tokens yourself. Pass exactly one as auth to new PlanningCenter() (or to any
create{Product}Client()); mixing them throws a PcoError that tells you what’s wrong.
| Strategy | Shape | Use it for |
|---|---|---|
| Personal access token | { applicationId, secret } |
Scripts and servers working with your own organization |
| OAuth | { accessToken, refreshToken?, clientId?, clientSecret?, expiresAt?, onTokenRefresh? } |
Apps that other organizations connect to |
| Token provider | { getAccessToken } |
You already store and refresh tokens elsewhere |
See Planning Center’s authentication docs.
Personal access tokens
Create one at api.planningcenteronline.com/oauth/applications. It acts as the person who created it, with their permissions, and is sent as HTTP Basic auth.
import { PlanningCenter } from '@mackenly/planningcenterkit';
const pco = new PlanningCenter({
auth: { applicationId: process.env.PCO_APP_ID!, secret: process.env.PCO_SECRET! },
});OAuth
Using tokens you already have
const pco = new PlanningCenter({
auth: {
accessToken: saved.accessToken,
refreshToken: saved.refreshToken,
expiresAt: saved.expiresAt, // milliseconds since the epoch, or a Date
clientId: process.env.PCO_CLIENT_ID!,
clientSecret: process.env.PCO_CLIENT_SECRET!,
onTokenRefresh: async (tokens) => {
await db.saveTokens(userId, tokens); // tokens.accessToken, tokens.refreshToken, tokens.expiresAt
},
},
});How refresh works:
- Pass
refreshToken,clientId, andclientSecrettogether to enable automatic refresh (all three or none; anything else throws). - The client refreshes about a minute before
expiresAt, and once after any401response, then replays the request. - Concurrent requests share a single refresh.
- Refresh tokens rotate. Every refresh returns a new refresh token and the old one stops
working. The client keeps the new tokens in memory, but you must persist them in
onTokenRefresh, or after a restart you’ll be holding a dead refresh token and the user will have to authorize again. IfonTokenRefreshthrows, the request that triggered the refresh fails with that error (the new tokens are still used in memory). - Access tokens last 2 hours; refresh tokens are honored for up to 90 days.
If you pass only accessToken, it’s used as-is until it expires.
When refresh fails (for example, the user revoked access), you get a PcoOAuthError:
import { PcoOAuthError } from '@mackenly/planningcenterkit';
try {
await pco.people.people.list();
} catch (err) {
if (err instanceof PcoOAuthError && err.error === 'invalid_grant') {
// The refresh token was already used or revoked: send the user through OAuth again.
}
throw err;
}Running the authorization flow
The helpers in @mackenly/planningcenterkit/oauth (also exported from the main entry) work on
their own, so you can use them in route handlers without creating a client.
import {
createPkceChallenge,
exchangeCodeForToken,
getAuthorizationUrl,
} from '@mackenly/planningcenterkit/oauth';
const redirectUri = 'https://example.com/auth/complete';
// GET /login
export async function login(): Promise<Response> {
const { codeVerifier, codeChallenge } = await createPkceChallenge();
const state = crypto.randomUUID();
// Save state and codeVerifier in the user's session (an encrypted cookie, a KV entry, ...).
await db.saveSession({ state, codeVerifier });
const url = getAuthorizationUrl({
clientId: process.env.PCO_CLIENT_ID!,
redirectUri,
scopes: ['people', 'services'],
state,
codeChallenge,
});
return Response.redirect(url, 302);
}
// GET /auth/complete?code=...&state=...
export async function complete(request: Request): Promise<Response> {
const url = new URL(request.url);
const session = await db.loadSession(url.searchParams.get('state'));
if (!session) return new Response('Unknown login attempt', { status: 400 });
const tokens = await exchangeCodeForToken({
clientId: process.env.PCO_CLIENT_ID!,
clientSecret: process.env.PCO_CLIENT_SECRET!,
code: url.searchParams.get('code')!,
redirectUri,
codeVerifier: session.codeVerifier,
});
await db.saveTokens(userId, tokens);
return Response.redirect('https://example.com/', 302);
}Notes:
scopesare product names:api,calendar,check_ins,giving,groups,home,people,publishing,registrations,resources,services, plusopenidfor an OIDCid_token. They’re exported asPCO_OAUTH_SCOPES. The Webhooks API needs no scope.- PKCE is optional for confidential apps but recommended. Planning Center supports
S256only. Public apps (no client secret) must use PKCE and can omitclientSecretfrom the exchange. getAuthorizationUrlalso acceptsnonceandprompt('login'or'select_account').- A complete runnable server is in examples/oauth-flow.ts.
Other OAuth helpers
import { introspectToken, normalizeTokens, refreshAccessToken, revokeToken } from '@mackenly/planningcenterkit/oauth';
const clientId = process.env.PCO_CLIENT_ID!;
const clientSecret = process.env.PCO_CLIENT_SECRET!;
// Refresh manually (when you don't use automatic refresh). Persist the result: the old refresh token is now dead.
const fresh = await refreshAccessToken({ clientId, clientSecret, refreshToken: saved.refreshToken });
// Disconnect: revoking the refresh token also revokes its access tokens.
await revokeToken({ clientId, clientSecret, token: fresh.refreshToken!, tokenTypeHint: 'refresh_token' });
// Check a token.
const { active, scope } = await introspectToken({ clientId, clientSecret, token: fresh.accessToken });
// Convert a raw stored token response ({ access_token, expires_in, created_at, ... }).
const tokens = normalizeTokens({ access_token: 'abc', refresh_token: 'def', expires_in: 7200, created_at: 1767225600 });Every OAuth helper accepts fetch, baseUrl, and signal options.
Token provider
If tokens live in another system that refreshes them, give the client a function. It’s called before every request attempt and must return the current access token:
const pco = new PlanningCenter({
auth: { getAccessToken: () => tokenStore.getFreshToken(userId) },
});The client doesn’t refresh provider tokens itself, so a 401 is returned to you as a
PcoAuthenticationError.
One client per user
A PlanningCenter instance holds one set of credentials. In a multi-tenant app, create a client
per organization or user (they’re cheap: product clients are created lazily on first use) and
cache it for as long as the tokens are valid:
import { PlanningCenter } from '@mackenly/planningcenterkit';
const clients = new Map<string, PlanningCenter>();
async function clientFor(userId: string): Promise<PlanningCenter> {
let client = clients.get(userId);
if (!client) {
const tokens = await db.loadTokens(userId);
client = new PlanningCenter({
auth: {
accessToken: tokens.accessToken,
refreshToken: tokens.refreshToken,
expiresAt: tokens.expiresAt,
clientId: process.env.PCO_CLIENT_ID!,
clientSecret: process.env.PCO_CLIENT_SECRET!,
onTokenRefresh: (fresh) => db.saveTokens(userId, fresh),
},
});
clients.set(userId, client);
}
return client;
}Custom hosts
baseUrl changes the API origin (and the OAuth endpoints used for refresh), and uploadUrl the
file upload endpoint. The client refuses to send credentials to any other origin, even when a
response’s pagination links point there.