Products

Flow FrameworkOpen-source, one codebase for every chat Unified APIiMessage, WhatsApp and Telegram Flow CloudHosting, tests and observability

Ships to

WhatsAppiMessageTelegramChatGPTClaudeMuseInstinctMCPCLI
PricingBlogDocs GitHub

Developer guideiMessage API7 min read

iMessage API security checklist

A Flow iMessage API security checklist: key handling, webhook verification, retention and deletion, file safety and keeping agent tools in check.

By FlowPublished Updated

The short answer

Flow gives your agent dependable messaging primitives, but security is still your product decision. Keep keys on the server, verify every webhook, deduplicate events, limit retention and give your agent narrow tools with confirmation before any change.

Building on the iMessage API? Build on iMessage with Flow: one agent for iMessage, WhatsApp and Telegram. New to it? Read the iMessage API guide.

Keys

  • Server side only. A key in a browser or mobile app is a key anyone can read. Flow’s docs say never to put a key in browser or mobile code.
  • Environment variables, not source. Use FLOW_MESSAGING_KEY in the environment or a .env file that is in .gitignore. The setup command adds .env to .gitignore for you.
  • Keep test and live keys apart. Test keys (fk_test_...) and live keys (fk_live_...) belong to different modes. Keep the live key in its own variable, so it does not replace your test key.
  • Protect the claim token. The claim_token from a test key lets a person claim the app, so treat it like the key.
  • Rotate on exposure. If a key may have leaked, revoke it and make a new one.

From Flow’s keys docs. Anyone, including a coding agent, can get a test key with no account, which is why a test key has small limits and expires after seven days.

Webhooks

A webhook endpoint is a public URL that triggers actions. Verify every delivery.

  • Verify the signature on the raw body. Flow signs with HMAC-SHA256 in a Flow-Signature header. A parsed and re-serialised body will not match.
  • Reject old timestamps. Flow’s check rejects timestamps more than five minutes from your clock.
  • Compare in constant time.
  • Deduplicate on the event ID. Deliveries are at least once.
  • Rotate secrets with an overlap. Flow keeps the old secret signing for a period, one day by default, so you can deploy the new one without dropping events.
  • Use HTTPS. The URL must be public HTTPS.

The code and the details are in iMessage webhooks: signing, retries and ordering.

Data retention and deletion

  • Know your retention. On Flow, message content and files are kept for your plan’s retention, 30 days by default. After that, content is removed and files deleted.
  • Delete on request. DELETE /v1/contacts/{contact_id} erases the contact’s name and address, the content of their conversations, their files and their events. It answers 204, and repeating it is safe. It cannot be undone.
  • Handle contact.deleted. Your endpoints receive it once. Delete what you keep about them too.
  • Know what stays on the channel. Flow cannot delete the chat on the person’s own device.
  • Do not log message text you do not need. Your own logs are outside any provider’s retention.

From Flow’s retention docs. Sensitive data needs more: do not send protected health information through any iMessage API unless your provider has agreed in writing to handle it and your counsel agrees. Flow does not publish a compliance report, does not allow regulated data on iMessage (health information, card or bank account numbers, government IDs), and refuses iMessage for HIPAA accounts.

Files and inbound content

  • Check types and sizes before you pass a file to a model or store it.
  • Know whether documents are scanned. On Flow, documents are scanned for malware, and a failure answers 422 file_blocked.
  • Treat inbound text as untrusted. A customer can write anything, including instructions meant for your model. Do not let message text change what tools the agent may use.

iMessage API: media, files and voice notes covers the file side.

Agent tools and identity

An agent that can take actions needs more care than one that only answers.

  • Narrow, typed tools. Define each action with clear inputs. Avoid a general “run this” tool.
  • No shell or file access for a customer-facing agent. With the Claude Agent SDK, set tools: [] to turn the built-in tools off.
  • Read before write, confirm before you act. Ask “Shall I move it?” and act on the yes. Say it is done only when your backend says so.
  • Verify identity before private data. A matching display name or an unverified phone number is not proof of who is writing. Link a messaging identity to an account through a deliberate sign-in.
  • Do not assume a number. An iMessage handle can be a phone number or an email address.
  • Use idempotency keys so a retry never repeats an action. See idempotency keys.
  • Review agent-written code like any other code before it handles customers.

Build an iMessage AI agent covers the tool design.

What to ask your provider

  • Which compliance reports do you hold, and can I see the current one?
  • How long do you keep message content, and can I delete one person’s data?
  • How are webhooks signed, and can I rotate secrets without downtime?
  • What happens to my line if Apple restricts it?
  • Do you scan files?

The provider comparison lists what each publishes.

Frequently asked questions

Where should I keep an iMessage API key?

On the server only, in an environment variable or a git-ignored .env file. Flow's docs say never to hard-code keys, never commit .env and never put a key in browser or mobile code.

How do I secure webhooks?

Verify the signature on the raw request body with your endpoint secret, reject old timestamps, and deduplicate on the event ID. Flow signs with HMAC-SHA256 and rejects timestamps more than five minutes from your clock.

How long does Flow keep message data?

Message content and files are kept for your plan's retention, 30 days by default. A contact and their data can also be deleted at any time through the API.

Can I delete a customer's messages?

Yes. On Flow, DELETE /v1/contacts/{contact_id} erases the contact's name and address, the content of their conversations, their files and their events. It cannot be undone, and Flow cannot delete what the channel keeps on the person's own device.

How do I keep an AI agent's tools safe?

Give it narrow, typed tools, no shell or file access, read before write, and confirmation before any change. Do not link a phone number to an account unless the person is verified.

Does Flow publish a compliance certification?

No. Flow does not publish a compliance report, and it refuses iMessage for HIPAA accounts. Ask any provider for its current report and verify that it covers the product and data you plan to use.

Start hereiMessage API: a developer’s guideThe overview of how iMessage APIs work, and what to ask a provider. Developer guideSend iMessage programmaticallycurl, TypeScript and Python: get a key, receive a signed webhook, reply once and handle retries.Developer guideiMessage API without a MacWhy a hosted iMessage API removes the Mac, what the DIY relay costs you, and how to choose.Developer guideiMessage MCP serverTwo things people mean by it: a messaging MCP for your coding agent, and your product as an MCP server.Developer guideiMessage API for Node.js and TypeScriptInstall the SDK, stream inbound messages, verify signed webhooks in Express and reply safely.Developer guideiMessage API for PythonStream inbound events, verify signed webhooks in FastAPI and reply with idempotency keys.Developer guideiMessage API for GoPoll events, reply and verify signed webhooks with the standard library, no SDK needed.

All posts: the Flow blog. The Flow docs have the reference.

From reading to building

Your agent, on iMessage and everywhere else.

Flow gives your agent an iMessage line, and the same code answers on WhatsApp and Telegram and works as an MCP server and CLI. See how it works on iMessage.

Build on iMessage with Flow