Developers, the API and installed apps

Sidebar: Account → Settings → Developers. One page with four tabs: Installed apps, API keys, Your apps and Activity.

It appears only where the developer platform is switched on for your workspace — if you don't see Developers under Settings, it isn't available to your workspace yet. Owners and admins see the page. Agents and clients don't: API keys and apps can read your contacts and send messages, so the page tells them only an owner or admin can see it.

What can an app or an API key do in my workspace?

Only what it was given permissions for, and only in the workspace it belongs to — a key or an install can never reach another workspace, even one you own. Reading and changing are separate permissions:

What it can never do, whatever it was given:

• Send a message that your own automations couldn't. A start goes through the same checks as a start from the Inbox: opt-outs, permission on record, the 24-hour messaging window, your sending limits and a workspace pause all still apply, when the message is sent.
• Grant itself more. An app keeps the permissions an owner approved until an owner approves again.
• Use a signed-in browser. The API accepts only an API key or an app's access token.
• Keep working after the person who granted it stops being the workspace owner. Its requests are refused until a current owner approves it again.

Changes made through the API don't trigger your field changed rules, the same as editing a contact by hand.

Install an app

An app's developer sends you to hyperDM to approve it. The screen shows:

• the app's name, description, support email and privacy policy, and whether it's Reviewed and published (with its version) or a Test install — not reviewed by hyperDM;
• Installing into — your active workspace. To install into a different one, switch workspace in the sidebar first, then open the link again;
• what it can see, change and send, with a warning on anything that sends;
• where you'll be sent afterwards.

1. Read the permissions.
2. Click Allow and install (or Allow again if it's already installed). Only the workspace owner sees this button; anyone else sees Cancel and return.
3. You're sent back to the app, which finishes connecting.

Click Cancel to go back without installing anything. If the page says This app can't be installed, nothing was installed and nothing was sent to the app — the message says why (an unknown app, an address the app didn't register, or an app hyperDM hasn't published or has suspended).

If an app's permissions change while the screen is open, clicking Allow says so and reloads: review them again before allowing.

See what an installed app can do, and revoke it

1. Open Settings → Developers → Installed apps.
2. Each app shows its version (or Test install), when it was Last used, who approved it and when, and its support email. Expand permissions granted to see the list.
3. Click Revoke, then Revoke access.

Revoking takes effect on the app's next request: its tokens stop working and it can't read or change anything until an owner installs it again. Automations it already started keep running, and nothing already sent is undone. Revoked apps are listed under Show uninstalled.

"Version N of this app asks for more" means the developer published a version that needs extra permissions. Your install keeps only what you approved; it gets more only if the app sends you through its approval again and the owner allows it.

Suspended by hyperDM means we stopped the app everywhere. Its requests are refused until the suspension is lifted — revoke it if you don't want it back.

Create, rotate and revoke an API key

An API key lets your own code call the API for this workspace.

1. Open Settings → Developers → API keys and click Create API key.
2. Give it a Name, choose its Permissions (read and change are listed separately) and when it Expires (never, 30 days, 90 days or a year).
3. Click Create key. The key is shown once — click Copy, store it somewhere safe, then I've stored it. hyperDM keeps only a fingerprint of it and its last four characters.

The list shows each key masked (hdm_sk_… and its last four characters), its status, who created it, when it was Last used and when it expires.

• Rotate creates a new key with the same name and permissions and stops the old one immediately. The new key is shown once.
• Revoke stops it immediately. This can't be undone.

A workspace can have up to 25 active keys. Revoked, replaced and expired keys are listed under Show … revoked, replaced or expired.

See the activity log and recent requests

Settings → Developers → Activity has two lists:

• Access changes — every key created, rotated or revoked, every app installed, approved again or revoked, and every review decision about apps you build. No key or secret is ever recorded.
• Recent API requests — the last 50 requests made with a key or an installed app: which one, the method and endpoint, and the result code. Request bodies are never stored, and the log is kept for 30 days.

Neither list says an app is working correctly. They show what happened.

Build an app other workspaces can install

1. Open Settings → Developers → Your apps and click Create app. Name it and click Create app.
2. Copy the Client id, Client secret and Webhook signing secret shown next. The secrets are shown once. Click I've stored it to open the app's editor.
3. Under Details, fill in the description, Support email, Homepage and Privacy policy.
4. Under Permissions, tick only what the app needs.
5. Under Callbacks, add the Redirect URLs your app receives the approval code on (one per line, up to 5, https:// only — a loopback address such as localhost may use http:// while you test) and, optionally, a Webhook URL.
6. Click Save. If something's wrong, the fields say what, and nothing is saved until it's fixed.

If someone else saved the app while you were editing, you'll be asked to Discard mine, load theirs or Save mine over theirs.

Test an app in your own workspace

The workspace you build an app in is its test workspace: it can install the saved draft before hyperDM reviews anything. No other workspace can.

1. Save your changes.
2. In Test in this workspace, click Install the draft here.
3. Approve it on the consent screen. hyperDM sends an approval code to your first redirect URL.

Changing the draft afterwards doesn't change what the test install was granted — click Approve the draft again to pick up new permissions.

Prove you own your app's callback domains

Before submitting, prove you control every domain in your redirect and webhook URLs.

1. In Callback ownership, copy the verification line.
2. Serve it as a plain-text file at /.well-known/hyperdm-app-verification.txt on each domain listed.
3. Click Check now. Each domain shows Verified or why it isn't: the file isn't there, it doesn't contain the line, it redirected, or the address is private.

A verification counts for 30 days.

Submit an app for review, and what the states mean

Other workspaces can install only a version hyperDM has reviewed and published.

1. Save the draft, and make sure every check under Publication passes: the manifest is complete, every callback domain is verified, there's a support email and privacy policy, and the app is built for a supported API version. Apps that can send messages or read personal data are marked for the reviewer to look at closely.
2. Click Submit for review, then confirm. The saved draft becomes a new, frozen version.

Only one version can wait for review at a time. Installs of an earlier version keep what their owners approved: permissions a new version adds need each owner to approve again. hyperDM can suspend an app that's misused; its tokens stop working everywhere until the suspension is lifted.

Connect an app with OAuth

Apps use the OAuth 2.0 authorization code flow, as confidential clients.

1. Send the workspace owner to https://app.hyperdm.app/settings/developers/authorize with response_type=code, client_id, an exact redirect_uri, state, and optionally scope (space-separated, a subset of your manifest) and a PKCE code_challenge with code_challenge_method=S256.
2. After they allow it, your redirect URL receives code and state. If they cancel, it receives error=access_denied.
3. Within 10 minutes, POST /api/v1/oauth/token with grant_type=authorization_code, the code, the same redirect_uri, code_verifier if you sent a challenge, and your client id and secret (HTTP Basic or form fields). The answer has an access_token (1 hour), a refresh_token, the granted scope, workspace_id and installation_id.
4. Refresh with grant_type=refresh_token. Every refresh returns a new refresh token; using an old one again revokes the whole chain, and the owner has to approve the app again.

A code works once — presenting it twice revokes the tokens it gave. POST /api/v1/oauth/revoke with token revokes a token you no longer need. Rotating your client secret stops the old secret at once; tokens already issued keep working until they expire.

Receive webhooks about installs

If your app has a Webhook URL, hyperDM sends it a JSON POST when a workspace installs the app (app.installed), approves it again (app.authorization_updated, with previous_scopes), or revokes it (app.uninstalled). Each carries installation_id, workspace_id, client_id and scopes.

• Verify the signature. The HyperDM-Signature header is t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of <t>.<raw body> keyed with your webhook signing secret.
• Answer 2xx. Anything else, a redirect or no answer within 8 seconds is retried — up to 6 attempts over about 9 hours — then marked failed. A URL that resolves to a private address fails at once.
• The editor's Webhook deliveries list shows each delivery's status and attempts.

Call the API: authentication, endpoints and formats

Base URL https://app.hyperdm.app/api/v1. Send Authorization: Bearer <API key or access token>. The machine-readable description is at /api/v1/openapi.json.

• Lists are newest first, up to limit (1–100, default 50). Pass the response's next_cursor as cursor for the next page; has_more says whether there is one.
• Field values are typed: a number field takes a number, a boolean true/false, a date YYYY-MM-DD, a datetime an ISO 8601 timestamp with a zone, a List an array of strings; null clears. If any value is wrong, nothing in the request is written. The API creates text, number, boolean, date and datetime fields; create Lists in the app.
• Starts answer started (the first message was delivered), started_quietly (it opens with a step that sends nothing), started_held (a sending limit held the first message, and it won't be sent later) or, for a retry, already_started — whatever became of that run since. A retry answers start_refused only when the first attempt's first message was refused and nothing went out.

Errors, rate limits and retries

Errors look like {"error": {"type": "...", "code": "...", "message": "...", "request_id": "req_..."}}. Quote the request_id when asking for help.

• Rate limits: 120 requests a minute per key or installed app, 600 a minute per workspace, and 30 automation starts a minute per key or app. Every response has RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; a 429 has Retry-After.
• Idempotency: send an Idempotency-Key header on changes — it's required on automation starts. Retrying with the same key and body returns the first answer (marked Idempotent-Replayed: true) for 24 hours and doesn't do the work again. The same key with a different body is refused. A 500 releases the key, so retry with it.
• Bodies are JSON objects of at most 64 KB.

Common questions

I don't see Developers in Settings. It's only where the developer platform is switched on for your workspace, and only for owners and admins.

An admin can see the page but can't install an app or create a key. Granting access is the owner's decision. Admins can revoke.

My key stopped working and I didn't revoke it. It expired, someone rotated or revoked it (check Activity), or the person who created it is no longer the workspace's owner — the owner needs to create a new key.

The app says it can't start an automation. The answer's code says why: the contact opted out, has no permission on record or is outside the messaging window (contact_unreachable); automations are paused (workspace_paused); the automation isn't live, is on another channel or only starts from a comment or a checkout (incompatible_automation); or the contact is already in it (already_running).