Skip to main content

Developer API Overview

Chastify supports account linking, extensions installed on locks, and personal scripts. Start by choosing the integration you need: each uses different credentials and permissions.

Automating your own lock?

Start with External API & Programs. A personal, user-wide DEV key can call the API without an iframe or installed extension, subject to your role and Developer API safeguards.

For the built-in block editor, triggers, variables, and test tools, see Programmable Locks.

What This API Is For​

Installed extensions add an experience to a Chastify lock session. Depending on their permissions, they can read session context, store extension state and files, add lock-card actions, manage unlock requirements, and request supported lock or device actions.

Account linking is a separate flow. Use OAuth account linking for a Connect Chastify button that returns a verified account identity and, with consent, read-only lock information.

What You Can Build​

  • A dashboard or Discord integration: connect users through OAuth, then read the information they approved.
  • An iframe interface: show session data, display stored media, or collect setup options inside Chastify.
  • A backend-supported lock extension: validate game results or task progress on your server, then request permitted rewards, punishments, or unlock-blocker updates.
  • A personal script: use your own DEV key to automate an active lock where you are the wearer or current keyholder.

Read Extension API Features for unlock blockers, recurring requirements, rewards, and punishments. A backend is necessary for trusted mutations, but does not override the user's role or lock permissions.

Choose Your Mode​

GoalCreate in Developer APICredentials and next guide
Link accounts to a dashboard or botCreate OAuth appApp-scoped key for code exchange; the resulting user access token for reads. See OAuth account linking.
Build a read-only runtime UI or setup screenCreate extensionUse the parent iframe bridge. See Iframe Quickstart.
Change an installed extension's state or request lock actionsCreate extension, plus your own backendApp-scoped DEV key and a valid iframe launch mainToken. See backend flow.
Automate locks using your own accountCreate a User-wide DEV keyPersonal bearer key. See External API & Programs.

OAuth apps do not need iframe URLs and cannot be installed as lock extensions. Never ask third-party users to give your service their personal DEV keys as a replacement for OAuth.

Keep trusted decisions on your backend

Iframe JavaScript, hash payloads, and launch tokens are visible to the person using the page. Validate claimed progress on your backend before granting rewards or clearing requirements. Keep the app-scoped DEV key out of browser code.

First 10 Minutes (Iframe Mode)​

  1. Create an extension and configure its hosted iframe URL and allowed origins.
  2. Enable the extension on a test lock and open its page inside Chastify.
  3. Decode the launch payload from location.hash. Check bridge.nonce, bridge.parentOrigin, sessionId, and lockId.
  4. Send session.get through the bridge, then try state.get.
  5. Add automatic height updates and theme support for light and dark mode.

Send a unique request ID and the current launch nonce:

{
"type": "chastify:ext:req",
"v": 1,
"id": "unique-request-id",
"nonce": "nonce-from-hash",
"action": "session.get",
"payload": {}
}

Use window.parent.postMessage(request, parentOrigin). Accept responses only from the expected parent window and origin, with the matching request ID, type: "chastify:ext:resp", and v: 1. Successful responses contain ok: true and data; failures contain ok: false and error.

The Iframe Quickstart provides the bridge helper and a complete bootstrap example. Opening your hosted page directly does not supply the Chastify launch context.

Core Actions To Learn First​

Runtime bridge commandPurpose
session.getRead the current session, role, scopes, configuration, and lock context.
state.getRead this extension session's JSON state. Your backend writes it.
metadata.getRead unlock blockers and home actions.
regularActions.getRead configured recurring-action status; unavailable when that feature is disabled.
files.capabilities, files.list, files.getCheck storage availability and read stored files. Refresh signed URLs with files.get.

Runtime state writes, file uploads/deletions, action submissions, and lock mutations use backend APIs. Setup file uploads use a separate staged-file workflow; see Extension File Storage.

Full API URLs (Supported)​

The API base is https://chastify.net. The tables below show paths relative to that origin.

Extension session APIs (/api/extensions/*)​

Installed extension calls use /api/extensions/sessions/:sessionId. The ID comes from the launch payload; it is not interchangeable with lockId or appId.

Path after /api/extensions/sessions/:sessionIdRead methodBackend mutation method
No suffixGET—
/stateGETPUT, PATCH
/metadataGETPATCH
/regular-actionsGETPOST
/regular-actions/config—PATCH
/files/capabilitiesGET—
/filesGETPOST
/files/:fileIdGETDELETE
/action, /device-command—POST
/logs/custom, /notifications/custom—POST
/requirements/progress—POST

For example, a state read is GET https://chastify.net/api/extensions/sessions/:sessionId/state. Inside the iframe, use the corresponding bridge command; Chastify's parent makes the authenticated read.

For backend requests, send both headers:

Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEY
x-chastify-main-token: MAIN_TOKEN_FROM_IFRAME_HASH

Backend token APIs (/api/apps/v1/*)​

Personal automation sends Authorization: Bearer YOUR_USER_WIDE_DEV_KEY. Common routes are /session, /state, /metadata, /action, /lock/apply-time, /lock/freeze, /lock/unfreeze, /device-command, /logs/custom, and /notifications/custom. See External API & Programs for methods, request bodies, and selecting a target lock.

Two read endpoints also belong to account linking:

  • GET /api/apps/v1/me accepts an OAuth access token only.
  • GET /api/apps/v1/session accepts an OAuth access token with locks:read, or a user-wide DEV key with that scope.

OAuth access tokens cannot use the mutation routes. An app-scoped key alone cannot read another user's lock through these endpoints.

Iframe Bridge Commands​

The runtime bridge accepts the read commands in Core Actions. files.get takes { "fileId": "file_record_id" }; the other listed reads can use an empty payload.

Do not send state.patch, lock.applyTime, or other mutation names as runtime bridge actions: unsupported actions return unknown_action. Use your backend and the corresponding HTTP endpoint instead.

Resize messages use chastify:ext:resize; theme updates arrive as chastify:ext:ui. These are UI messages, not lock actions. The current window, origin, and nonce must match the current launch.

Backend Session API Examples​

To add five minutes, your backend can send this JSON to POST /api/extensions/sessions/:sessionId/action, using both authentication headers above:

{
"name": "add_time",
"params": 300
}

To remove five minutes, use "name": "remove_time" with "params": 300. A negative value with add_time does not remove time: that action uses the absolute amount.

Other examples:

RequestJSON body
PUT .../state{ "data": { "completed": 1 } }
PATCH .../state{ "data": { "completed": 2 } }
POST .../action{ "name": "freeze", "params": { "durationSeconds": 900 } }
POST .../action{ "name": "task.start_timer", "params": {} }

These examples illustrate the request shape, not permission to perform every action. See API Examples and the role rules below before implementing them.

Token, Scope, Revocation, and Audit Behavior​

Developer keys are backend secrets

Copy a new DEV key when it is created: the full value is shown once. If it reaches a browser bundle, public repository, or shared log, revoke it in Developer API and replace the credential used by your backend.

Iframe launch token (mainToken)​

  • Delivered in the runtime iframe hash when the extension opens.
  • Bound to the app, installed session, lock, user, and that user's role.
  • Snapshots the installed extension's currently allowed permissions. Later permission increases require a fresh launch; reductions take effect on the next request.
  • Expires after 10 hours. A new launch-token request revokes previous tokens for that same user and extension session, so a token can stop working earlier.
  • Sent by your iframe to your backend, then forwarded as x-chastify-main-token.
  • Insufficient on its own for privileged mutations. It is browser-visible context, not your backend secret.

App-scoped Developer API key​

Choose Developer API → New key → Key type: App-scoped, then select the application. Keep the key on the backend and send it as the bearer credential.

For an installed extension, pair it with that app's current mainToken. For OAuth code exchange, use it with the consented authorization code and PKCE verifier as described in OAuth account linking. Those are separate authentication flows.

Treat the key as a long-lived secret and revoke it when no longer needed.

User-wide Developer API key​

Choose Key type: User-wide for personal scripts. It is not tied to one extension or one launch and can target active locks where the key owner is the wearer or current keyholder. Normal role and lock restrictions still apply.

The account's Developer API safeguards can block creating keys while locked or block using personal keys as a locked wearer. The UI and API report these restrictions; plan your integration setup before beginning a lock. This key cannot replace an app-scoped key for installed third-party extensions.

Revocation​

Revoke a DEV key in the Developer API page to stop new requests using it. A revoked key can then be permanently deleted. Reopening the iframe obtains fresh launch context; do not treat mainToken as a durable credential.

Users disconnect OAuth access through Manage connected applications. Revoking the app key used for OAuth exchange also invalidates access tokens issued through that key; see the OAuth guide before rotating an integration's credentials.

Scopes and Roles​

Installed-session access is the intersection of the launch grant's scopes, the app's current allowed scopes, the installed extension's current scopes, and the DEV key's scopes. Reads require locks:read; backend writes require locks:write in all four sources as well as valid backend credentials. Missing or empty grant scopes authorize nothing.

Existing read-only launch tokens remain read-only. Reopen the extension in Chastify to obtain a fresh launch with its currently allowed permissions. Renewing a token through the backend cannot increase the original grant's permissions.

The launch role is checked against the user's current lock role on each request. Backend credentials do not turn a wearer's launch into a keyholder launch. In particular, the installed-extension API requires a keyholder launch for remove_time, unfreeze, toggle_freeze, settings.patch, task.complete, and hygienic_unlock.start. Shared locks have additional keyholder/trust restrictions, including time changes and freezing.

Audit and Limits​

The Developer API page shows key last-use information. Custom log calls add lock-history entries, while custom notification calls request delivery to the wearer, keyholder, or both. An accepted notification request is not proof that the recipient saw it.

Handle the documented rate limits, validation failures, and permission errors. Keep your backend's own record of verified outcomes and submitted actions; a timeout does not prove that a mutation failed. Avoid blindly repeating time changes or punishments after an uncertain response.

Supported Command Values​

/api/extensions/sessions/:sessionId/action and /api/apps/v1/action​

The name field accepts:

add_time, remove_time, freeze, pillory, pillory.end,
unfreeze, toggle_freeze, settings.patch,
task.assign, task.start_timer, task.complete,
hygienic_unlock.start

Each action has its own parameters and permission checks. Task actions require the Tasks module; completing a timed task successfully requires its timer to finish. Hygienic opening must be enabled and cannot start during an existing hygienic opening or soft emergency release. Configured maximums, trust restrictions, and current lock state can reject an otherwise valid request.

session.get lock data helpers​

Session responses include lockData fields such as frozen, trusted, taskAssigned, timeLockedSeconds, timeRemainingSeconds, taskPoints, and lockTitle. taskAssigned means an open task run exists.

The installed-extension and /api/apps/v1/session responses are not identical. The latter can return null for timing fields hidden from the wearer; do not convert that to a displayed zero or treat it as an unlock decision. Last-seen timestamps are null when the corresponding user disables online status. Read the response's display settings before showing lock information.

Module status​

Both session responses include a top-level modules object. This applies to session.get / GET /api/extensions/sessions/:sessionId and GET /api/apps/v1/session with either an OAuth access token or a personal DEV key. Existing response fields remain available.

{
"modules": {
"builtIn": {
"penalty": false,
"tasks": true,
"wheel": false,
"dailyVerification": true,
"pillory": false,
"publicVoting": false,
"dice": false,
"chess": false,
"blackJack": false,
"slotCasino": false,
"poker": false,
"geofence": false,
"cardGame": false,
"casinoGames": true,
"hygienicUnlock": true
},
"extensions": [
{
"sessionId": "65a000000000000000000001",
"appId": "65a000000000000000000002",
"slug": "example-extension",
"enabled": true
}
]
}
}
  • builtIn always includes the listed boolean flags, including disabled modules. These describe saved lock settings, not whether an action can run right now. Cooldowns, permissions, and other restrictions still apply.
  • blackJack, slotCasino, and poker describe the legacy module configurations. casinoGames describes the separate casino master switch, including the saved opt-out on older locks; it does not report each casino game's availability.
  • extensions lists installations on this lock, including disabled installations. It is [] when none are installed, not a catalog of every available extension. Each entry contains only identity and enabled status, without configuration, state, or credentials.
  • Use appId as the stable app identity and sessionId as the installation identity. IDs and slug may be null for legacy records. Slugs can change. A legacy installation without an explicit enabled flag uses the enabled default.

For example, once you have the session response:

const enabledBuiltIn = Object.entries(session.modules.builtIn)
.filter(([, enabled]) => enabled)
.map(([name]) => name);
const disabledBuiltIn = Object.entries(session.modules.builtIn)
.filter(([, enabled]) => !enabled)
.map(([name]) => name);
const enabledExtensions = session.modules.extensions.filter((extension) => extension.enabled);
const disabledExtensions = session.modules.extensions.filter((extension) => !extension.enabled);

GET /api/apps/v1/me remains a profile response. Request /session with locks:read for module status.

Device Commands​

Installed extensions use POST /api/extensions/sessions/:sessionId/device-command. Personal programs use POST /api/apps/v1/device-command. Device capabilities, user settings, and delivery availability still apply.

Use External API & Programs for request formats and Shock Delivery & Queues to understand queued delivery and stopping behavior. A successful command request is not a guarantee that a device has already executed it.

When creating an iframe extension, provide both the main iframe URL and setup iframe URL. Chastify opens the setup page to collect the lock's extension configuration:

  1. Chastify sends chastify:ext:setup:init with saved configuration and context.
  2. The setup iframe sends chastify:ext:setup:config updates using the current nonce.
  3. Before saving, Chastify can request the latest configuration with chastify:ext:setup:get_config.

Setup uses its own message channel and permissions. It can stage configuration files through chastify:ext:setup:req; this does not grant runtime upload or lock-action access. Follow Extension File Storage when attaching images to saved configuration.

Backend Token Flow (When You Need Server-Side Calls)​

For an installed extension:

  1. The user opens the extension in Chastify, which issues a launch token and includes it as mainToken in the iframe hash.
  2. The iframe forwards that launch context to your backend.
  3. Your backend validates the requested operation and any claimed outcome.
  4. It calls /api/extensions/sessions/:sessionId/* with the app-scoped DEV key and x-chastify-main-token.
  5. Handle expired, revoked, or role-mismatched tokens by obtaining a fresh user launch before submitting further work.

GET /api/extensions/sessions/:sessionId/auth is used by Chastify's authenticated parent UI to issue a launch token. It is not a runtime bridge command or a permanent background credential.

A backend does not create permanent session access

Your server can run jobs and receive webhooks while the iframe is closed. Calls back into an installed extension still require a valid launch token, and that token can expire or be revoked. Store pending work on your backend when no valid launch is available; revalidate it before submitting after a new launch. Do not promise continuously authorized unattended mutations from an app-scoped key alone.

Personal automation instead uses a user-wide DEV key; OAuth reads use the consented user's access token. Neither flow needs an iframe launch, and neither changes the installed-extension credential rules.

Backend vs Cloudflare Pages (No Server)​

Use Cloudflare Pages (no backend server) when:​

Use static hosting for a setup page, read-only runtime interface, or prototype. Its JavaScript runs while the page is open and uses the iframe bridge for permitted reads. Browser storage or UI state is not trusted proof of completion.

Use a backend server when:​

Use a backend for state writes, verified progress, privileged requests, external databases, webhooks, and scheduled processing. Keep credentials there and design jobs around the launch-token limits above. Hosting an iframe on a static host and operating a backend are compatible choices.

Common Issues​

Error or symptomWhat to check
No bridge responseOpen inside Chastify; check the current nonce, parent window, target origin, and configured allowed origins.
unknown_actionThe requested mutation is not a runtime bridge command. Use its backend HTTP endpoint.
main_token_required, expired_main_token, revoked_main_tokenSupply the current launch token from a fresh extension opening.
app_scoped_key_required, user_wide_dev_key_requiredMatch the key type to the API family.
server_credentials_requiredA launch token or first-party browser session is not sufficient for this mutation.
insufficient_scope, keyholder_role_required, trusted_keyholder_requiredCheck app/install/key scopes and the current launch role and lock permissions.
grant_role_mismatchThe lock role changed after the token was issued. Reopen with the appropriate current participant.
extension_not_enabled, lock_endedThe installed extension or lock is no longer available for the requested work.
dev_api_key_creation_blocked_while_locked, personal_dev_api_key_blocked_while_lockedAn account Developer API safeguard is active.
HTTP 429Follow Rate Limits and reduce request frequency.

See Troubleshooting for deeper diagnostics.

Next Guides​