An API key lets a developer, or a tool you run, use the Mateflow Open API to read and write your community's data. You create, replace, and revoke API keys under Admin → Settings → Integrations → API Access. Each key works for one community only.
Who can do this: Owners and admins. · Where: Web (admin console). · Plan: API access, and how many API requests a day your community can make, depend on your platform plan.
API keys are per community
API keys belong to a single community, and requests made with a key always act on that community. To connect several communities, create a key in each one's admin console.
The creator dashboard (app.mateflow.com) doesn't have API keys. Workspace-level keys there have been replaced by per-community keys. A community's Overview page in the dashboard links to its Integrations page.
Create an API key
- Go to Admin → Settings → Integrations and open the API Access tab.
- Click Generate New Key.
- Enter a Key Name that says what it's for, such as the tool that will use it and what it does. Expiry reminders name the key, so a clear name tells you which integration they're about.
- Optional: turn on Public content only, for example if you're giving the key to a third party to show public content. See Limit a key to public content below.
- Under Scopes & Permissions, tick only the permissions the integration needs. See the next section.
- Under Expires, keep No expiry or choose 30 days, 90 days, 180 days, or 365 days. The form shows the exact date and time the key stops working.
- Optional: under IP Whitelist (optional), enter the IP addresses or ranges allowed to use the key, separated by commas.
- Click Generate New Key.
- Copy the key from API Key Generated, store it somewhere safe, then click Done.
You can see the full key only once. If you lose it, create a replacement and revoke the old key.
You can't change a key's permissions, expiry, or Public content only setting after you create it. To change them, create a replacement (see below).
If the API Access tab shows an upgrade prompt, your platform plan doesn't include API access. The API Endpoint card shows the base URL for requests and your plan's daily request limit, which resets at 00:00 UTC.
API key scopes (permissions)
Permissions are laid out one row per kind of data, with a box for each action. Each box is one scope:
| Row | Box | What it allows |
|---|---|---|
| Community | Read | Read community profile, settings, and metadata |
| Content | Read | Read posts, feeds, replies, and search results |
| Content | Write | Create, edit, and delete posts and replies |
| Media | Read | Read signed URLs for existing media |
| Media | Upload | Request upload tokens; also covers reading signed media URLs |
| Spaces | Read | List spaces and read space details |
| Members | Read | Look up members and read basic profiles, including their access groups |
| Members | Invite | Invite people by email or by an invitation link |
Read on Community is ticked when the form opens. Ticking Write or Upload doesn't tick Read for you: a tool that only creates posts needs only Write on Content.
The Members row is listed under Sensitive access. Read lets the integration check whether an email address belongs to your community. With Invite, invitations are sent as the community owner unless the integration names another inviter, and invited people always join as members. API invitations can include access groups. See How access groups work.
Older keys may show All (legacy): they keep only the scopes that existed when they were created. Create a new key to use newer scopes.
Limit a key to public content
With Public content only turned on, a key sees only what a signed-out visitor sees. That includes the names and descriptions of Private spaces, but not of Secret spaces. Use it for a key you give to a third party, or for a tool that only shows public content.
Without it, a key can read as any member the integration names, including an admin, which reaches private and paid spaces. This applies to a key with only Read boxes ticked too, so read-only doesn't mean public-only.
A public-only key can have only Read on Community, Content, and Spaces. Turning the option on clears and disables the other boxes. Requests that name a member are refused. In the API Keys list, the key shows a Public only label. Keys you already have aren't affected.
When an API key expires
A key with an expiry stops working at the date and time shown when you created it. Requests that still use it are refused with an error that tells your developer the key has expired, rather than been revoked or mistyped.
In the API Keys list, the Status column counts down: Expires in 62 days, then hours on the last day. The countdown turns to a warning color when 14 days or fewer are left. Hover over it to see the exact date and time. Once the key has expired, its status reads Expired.
Owners and admins are reminded 14 days before a key expires, 1 day before, and when it expires. Each reminder is a notification plus an email, and says when the key was last used, so you can tell whether anything still depends on it. Click the notification to open API Access with the key highlighted. In the Mateflow app, the notification shows the same details but doesn't open anything. The email is sent right away, even if Email Notifications is off in your notification settings or your emails come as a Daily or Weekly digest. You don't get it by email only if you've turned off email for System Notices or set Notification summary email (previously called Email Digest Frequency) to Off. Revoked keys aren't reminded.
An expiry can't be extended. To keep an integration running, replace the key before it expires.
Replace an API key
Replacing gives you a new key with the same settings, so you can switch over without downtime: you can hold several keys at once. It's also the way to add an expiry to a key that doesn't have one.
- On the API Access tab, open the key's actions menu and click Create replacement. When a key has 14 days or fewer left, or has expired, its row also shows a Replace button.
- Create replacement key opens with the old key's name, permissions, Public content only setting, IP whitelist, and expiry filled in. Change anything you need, then click Generate New Key. If the old key has a permission this form can't grant, a "Not copied" note lists it, and the new key won't have it.
- Copy the new key and put it in your integration.
- Once the integration uses the new key and it shows a Last Used time, click Revoke old key under Next: retire the old key and confirm, or revoke the old key from the list later. Until you do, the old key still gets expiry reminders.
Both keys have the same name. Tell them apart by the key prefix under the name and the Created date.
Revoke an API key
- On the API Access tab, find the key under API Keys.
- Open its actions menu and click Revoke Key.
- Confirm. Revoking can't be undone, and any tool using the key stops working.
The list shows each key's Status (Active, Expired, or Revoked) and Last Used date. API requests don't appear in Delivery Logs, so Last Used is how you check whether a key is still in use. Disconnecting Slack, Discord, or Zapier doesn't revoke any API keys. Creating and revoking keys are recorded in Admin → Settings → Audit Log under Integrations.
Keep API keys secure
- Keep API keys on a server, not in a website or app that others can download, and send requests over HTTPS.
- Give each tool its own key with only the scopes it needs, so you can revoke one without breaking the others.
- Turn on Public content only for a key that only shows public content, especially one you give to a third party.
- Set an expiry and replace keys on a schedule, so a key that leaks without you knowing stops working on its own.
- Add an IP Whitelist when the tool calls from fixed addresses.
- Revoke a key right away if it may have leaked, then create a replacement.
Where to find the API documentation
The API reference covers endpoints, request and response formats, scopes, error codes, and code samples. On the API Access tab, the Developer documentation card has an Open documentation button that goes to mateflow.com/developers. Send that link to your developer. They don't need an account in your community, and the page is available even if your plan doesn't include API access.
Related articles
Was this guide helpful?