Automation & management

Service accounts & management tokens

A service account is a non-human identity — an agent, CI job, or trusted server integration — that manages your PokerWorks console resources without a person signing in. It authenticates with a management token (pw_mgmt_…), not a product API key.

Which key do I use?

pw_test_…Calculation API — Server-side test calculation calls.

pw_live_…Calculation API — Server-side live calculation calls.

pw_mgmt_…Automation & management — Server-side service-account automation. Never calculation calls or browser code.

How it works

Service accounts are owned by the organization, never by a user. Each one holds a granular set of scopes and zero or more management tokens. You create the service account and its tokens in the console, then hand the token to your automation.

Management tokens manage the console. They create projects, mint or revoke product API keys, read usage, and so on.
They never call the calculation API. Equity, ICM, and the other calculations require a product key (pw_test_ / pw_live_). A pw_mgmt_ token is rejected there by design.
They mint browser-safe launch sessions from trusted servers. For embed flows, your server uses a pw_mgmt_ token to create a short-lived session; the browser receives the returned launch URL, which carries a pwes_ launch secret in the URL fragment.

Scopes

Service accounts use least-privilege scopes. The launch set:

Scope	Grants
`org:read`	Read the organization, balances, settings, and visible projects/keys when paired with their read scopes.
`projects:read`	List projects visible to the token.
`projects:create`	Create projects. Tokens restricted to specific projects cannot create new projects.
`projects:update`	Update visible project settings, including name and allowed origins.
`product_keys:read`	List product API keys visible to the token. Secrets are never returned.
`product_keys:create`	Create reveal-once product API keys for allowed projects and environments.
`product_keys:revoke`	Revoke visible product API keys.
`usage:read`	Read usage summaries and recent requests for allowed projects/environments.
`billing:read`	Read wallet, balance, credit-pack, receipt, and auto-recharge summary state. Tokens with project restrictions cannot read organization billing.
`audit_log:read`	Read audit events. Tokens with project or environment restrictions cannot read organization-level audit events.
`playground:write`	Emit synthetic test-mode playground completions so webhook/result-verification recipes can be exercised on demand.
`embeds:read`	List approved embed products visible to the token.
`embed_sessions:create`	Create short-lived embed sessions from trusted server code.
`embed_sessions:read`	Read embed sessions visible to the token.
`rooms:read`	List and read rooms visible to the token.
`rooms:create`	Create rooms for allowed projects and environments.
`rooms:update`	Update room names, slugs, allowed origins, and basic branding.
`rooms:archive`	Archive rooms visible to the token.
`tournaments:read`	List and read tournaments in visible rooms.
`tournaments:create`	Create tournaments from approved presets.
`tournaments:update`	Update safe draft or scheduled tournament fields, and attach test-mode playground output to a published or scheduled tournament.
`tournaments:publish`	Publish or schedule test-mode tournaments; live publish remains gated until beta live guardrails are enabled.
`tournaments:cancel`	Cancel draft, scheduled, or published tournaments.
`tournaments:archive`	Archive draft or cancelled tournaments.
`ring_games:read`	List and read room-scoped ring-game catalog projections. Runtime operation, seats, waitlists, and gameplay state stay reserved.

Tokens can also be restricted to specific project IDs and environments (test, live). An empty project or environment restriction means organization-wide access for that dimension, subject to scopes. For playground tokens, restrict environments to test; the playground never emits live events.

Creating a token

Tokens are shown once at creation and hashed at rest — store them in a secret manager immediately. Tokens are always minted server-side; they are never generated in the browser.

Console users create them under Service accounts:

Create a service account with name and optional description.
Create a token under that service account with label, scopes, optional projectIds, optional environments, and optional expiresAt.
Store the returned secret immediately.

The token response returns:


Code
{
  "secret": "pw_mgmt_…",
  "token": {
    "id": "devsat_…",
    "serviceAccountId": "devsa_…",
    "label": "CI provisioning",
    "status": "active",
    "scopes": ["projects:read", "product_keys:create"],
    "projectIds": [],
    "environments": ["test"],
    "expiresAt": "2026-06-26T00:00:00.000Z",
    "masked": "pw_mgmt_…",
    "lastUsedAt": null
  }
}

The public secret appears only in this creation response. Later reads return metadata such as masked, prefix, status, scopes, restrictions, and timestamps, never the secret.

Rules & gotchas

A management token can't mint more management tokens (no privilege escalation).
Revoking a service account revokes all of its tokens immediately; revoke individual tokens to rotate without downtime.
Never put a management token in browser, mobile, embedded, or other untrusted client-side configuration. Use a backend-for-frontend or trusted server integration to perform Management API calls.
Money-moving and organization-admin actions are not available to service accounts.

Guide: Automate with a service account Webhooks

How it works

Management tokens manage the console. They create projects, mint or revoke product API keys, read usage, and so on.

They never call the calculation API. Equity, ICM, and the other calculations require a product key (pw_test_ / pw_live_). A pw_mgmt_ token is rejected there by design.

They mint browser-safe launch sessions from trusted servers. For embed flows, your server uses a pw_mgmt_ token to create a short-lived session; the browser receives the returned launch URL, which carries a pwes_ launch secret in the URL fragment.

Scopes

Service accounts use least-privilege scopes. The launch set:

Scope

Grants

org:read

Read the organization, balances, settings, and visible projects/keys when paired with their read scopes.

projects:read

List projects visible to the token.

projects:create

Create projects. Tokens restricted to specific projects cannot create new projects.

projects:update

Update visible project settings, including name and allowed origins.

product_keys:read

List product API keys visible to the token. Secrets are never returned.

product_keys:create

Create reveal-once product API keys for allowed projects and environments.

product_keys:revoke

Revoke visible product API keys.

usage:read

Read usage summaries and recent requests for allowed projects/environments.

billing:read

Read wallet, balance, credit-pack, receipt, and auto-recharge summary state. Tokens with project restrictions cannot read organization billing.

audit_log:read

Read audit events. Tokens with project or environment restrictions cannot read organization-level audit events.

playground:write

Emit synthetic test-mode playground completions so webhook/result-verification recipes can be exercised on demand.

embeds:read

List approved embed products visible to the token.

embed_sessions:create

Create short-lived embed sessions from trusted server code.

embed_sessions:read

Read embed sessions visible to the token.

rooms:read

List and read rooms visible to the token.

rooms:create

Create rooms for allowed projects and environments.

rooms:update

Update room names, slugs, allowed origins, and basic branding.

rooms:archive

Archive rooms visible to the token.

tournaments:read

List and read tournaments in visible rooms.

tournaments:create

Create tournaments from approved presets.

tournaments:update

Update safe draft or scheduled tournament fields, and attach test-mode playground output to a published or scheduled tournament.

tournaments:publish

Publish or schedule test-mode tournaments; live publish remains gated until beta live guardrails are enabled.

tournaments:cancel

Cancel draft, scheduled, or published tournaments.

tournaments:archive

Archive draft or cancelled tournaments.

ring_games:read

List and read room-scoped ring-game catalog projections. Runtime operation, seats, waitlists, and gameplay state stay reserved.

Creating a token

Tokens are shown once at creation and hashed at rest — store them in a secret manager immediately. Tokens are always minted server-side; they are never generated in the browser.

Console users create them under Service accounts:

Create a service account with name and optional description.

Create a token under that service account with label, scopes, optional projectIds, optional environments, and optional expiresAt.

Store the returned secret immediately.

The token response returns:

Code

{
  "secret": "pw_mgmt_…",
  "token": {
    "id": "devsat_…",
    "serviceAccountId": "devsa_…",
    "label": "CI provisioning",
    "status": "active",
    "scopes": ["projects:read", "product_keys:create"],
    "projectIds": [],
    "environments": ["test"],
    "expiresAt": "2026-06-26T00:00:00.000Z",
    "masked": "pw_mgmt_…",
    "lastUsedAt": null
  }
}

The public secret appears only in this creation response. Later reads return metadata such as masked, prefix, status, scopes, restrictions, and timestamps, never the secret.

Rules & gotchas

A management token can't mint more management tokens (no privilege escalation).

Revoking a service account revokes all of its tokens immediately; revoke individual tokens to rotate without downtime.

Never put a management token in browser, mobile, embedded, or other untrusted client-side configuration. Use a backend-for-frontend or trusted server integration to perform Management API calls.

Money-moving and organization-admin actions are not available to service accounts.

How it works

Scopes

Creating a token

Rules & gotchas

Related

How it works

Scopes

Creating a token

Rules & gotchas

Related