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.
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
| Goal | Create in Developer API | Credentials and next guide |
|---|---|---|
| Link accounts to a dashboard or bot | Create OAuth app | App-scoped key for code exchange; the resulting user access token for reads. See OAuth account linking. |
| Build a read-only runtime UI or setup screen | Create extension | Use the parent iframe bridge. See Iframe Quickstart. |
| Change an installed extension's state or request lock actions | Create extension, plus your own backend | App-scoped DEV key and a valid iframe launch mainToken. See backend flow. |
| Automate locks using your own account | Create a User-wide DEV key | Personal 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.
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)
- Create an extension and configure its hosted iframe URL and allowed origins.
- Enable the extension on a test lock and open its page inside Chastify.
- Decode the launch payload from
location.hash. Checkbridge.nonce,bridge.parentOrigin,sessionId, andlockId. - Send
session.getthrough the bridge, then trystate.get. - 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 command | Purpose |
|---|---|
session.get | Read the current session, role, scopes, configuration, and lock context. |
state.get | Read this extension session's JSON state. Your backend writes it. |
metadata.get | Read unlock blockers and home actions. |
regularActions.get | Read configured recurring-action status; unavailable when that feature is disabled. |
files.capabilities, files.list, files.get | Check 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/:sessionId | Read method | Backend mutation method |
|---|---|---|
| No suffix | GET | — |
/state | GET | PUT, PATCH |
/metadata | GET | PATCH |
/regular-actions | GET | POST |
/regular-actions/config | — | PATCH |
/files/capabilities | GET | — |
/files | GET | POST |
/files/:fileId | GET | DELETE |
/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/meaccepts an OAuth access token only.GET /api/apps/v1/sessionaccepts an OAuth access token withlocks: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:
| Request | JSON 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
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
}
]
}
}
builtInalways 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, andpokerdescribe the legacy module configurations.casinoGamesdescribes the separate casino master switch, including the saved opt-out on older locks; it does not report each casino game's availability.extensionslists 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
appIdas the stable app identity andsessionIdas the installation identity. IDs andslugmay benullfor legacy records. Slugs can change. A legacy installation without an explicitenabledflag 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.
Setup Page
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:
- Chastify sends
chastify:ext:setup:initwith saved configuration and context. - The setup iframe sends
chastify:ext:setup:configupdates using the current nonce. - 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:
- The user opens the extension in Chastify, which issues a launch token and includes it as
mainTokenin the iframe hash. - The iframe forwards that launch context to your backend.
- Your backend validates the requested operation and any claimed outcome.
- It calls
/api/extensions/sessions/:sessionId/*with the app-scoped DEV key andx-chastify-main-token. - 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.
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 symptom | What to check |
|---|---|
| No bridge response | Open inside Chastify; check the current nonce, parent window, target origin, and configured allowed origins. |
unknown_action | The requested mutation is not a runtime bridge command. Use its backend HTTP endpoint. |
main_token_required, expired_main_token, revoked_main_token | Supply the current launch token from a fresh extension opening. |
app_scoped_key_required, user_wide_dev_key_required | Match the key type to the API family. |
server_credentials_required | A launch token or first-party browser session is not sufficient for this mutation. |
insufficient_scope, keyholder_role_required, trusted_keyholder_required | Check app/install/key scopes and the current launch role and lock permissions. |
grant_role_mismatch | The lock role changed after the token was issued. Reopen with the appropriate current participant. |
extension_not_enabled, lock_ended | The 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_locked | An account Developer API safeguard is active. |
HTTP 429 | Follow Rate Limits and reduce request frequency. |
See Troubleshooting for deeper diagnostics.
Next Guides
- Extension Release & Beta Testing — developer and administrator controls, test users, and public availability.
- OAuth Account Linking — consented profile and lock reads.
- Iframe Quickstart and Iframe Theming — runtime UI setup.
- Extension API Features and API Examples — requirements and action payloads.
- Extension File Storage — setup and runtime file lifecycles.
- External API & Programs — personal automation.
- Webhooks, Rate Limits, and Troubleshooting.