API keysComing soon
Create a scoped API key for your own Matchai account, use it as a bearer token, keep it safe, rotate it and revoke it. For your own scripts and AI tools only.
An API key lets your own code act on your own Matchai account. It is the simplest way in: no app to register, no sign-in flow, one header on every request.
Use a key for your own scripts and your own AI tools. If you are building something that other professionals will use, use Connect with Matchai instead. See keys are for your own account.
What a key is
- It reaches exactly one account: the one that created it.
- It carries the scopes you chose when you created it, and nothing else. A key with
listings:readcannot change a listing. - It can be revoked at any time, by you, from Matchai.
- It belongs to your account's API access connection. API access is a Matchai Connector, like Claude or ChatGPT, and appears on the Connectors page. It is one connection however many keys you create, and keys are never billed one by one. The Connectors page shows what the connection costs.
Create a key
Open Settings → Connectors in Matchai and expand Advanced (for developers).
Go to API keys and create a key. Give it a name that says where it will run, such as "Listing sync" or "Office dashboard". You will be glad of it when you have five.
Choose its scopes. Pick only what the code needs. The scopes table lists them all.
Copy the key. Matchai shows it once. Afterwards the list shows only the key's name, its first characters, its scopes and when it was last used. If you lose a key, create a new one and revoke the old.
Key format
A key is matchai_ followed by a long random string of letters and digits. The random part has no dashes or underscores, so a double-click selects the whole key and one pattern finds it:
matchai_[A-Za-z0-9]+Treat a key as an opaque string. Do not parse it, and do not rely on its length. The matchai_ prefix is unique to Matchai, which lets secret scanners recognise a key that leaks into a repository.
Use a key
Send the key as a bearer token on every request:
curl https://api.matchai.co/v1/me \
-H "Authorization: Bearer $MATCHAI_API_KEY"A request that carries no key, or a key that was revoked or mistyped, answers 401.
Keep a key safe
- Keep it on a server you control. Read it from an environment variable or a secret manager. Never put it in browser code, a mobile app, a public repository, a log line or a chat message: anyone who can read it can act as you.
- Use one key per script or environment. A separate key for development and for production means you can revoke one without stopping the other.
- Give each key the fewest scopes that work. A script that only reads listings has no use for
contacts:write. - Revoke a key the moment you doubt it. A new key costs nothing. See revoke a key.
Rotate a key
Rotate keys on a schedule you can keep, and straight away if a key may have been seen. Several keys work at the same time, so rotation needs no downtime:
Create a new key with the same scopes.
Deploy it to the code that uses the old one.
Check in the keys list that the old key's last-used date has stopped moving.
Revoke the old key.
All the keys of one account share its API access connection, so they also share the connection's rate limit and its Energy limit.
Revoke a key
Open Settings → Connectors → Advanced (for developers) → API keys and revoke the key. Requests that use it answer 401 from then on.
To stop every key at once, disconnect API access on the Connectors page. A connection that ends stops all of its keys.
Keys are for your own account
A personal key is for your own account. Matchai's terms of service do not allow you to use personal keys to run a service for other people.
If other professionals will use what you build, such as a website builder, a CRM or an AI assistant, create a Matchai app and use Connect with Matchai. Each professional then sees what your app may do and who pays, agrees with one press of Allow, and can disconnect whenever they like. That is also what keeps their data theirs.
Final actions
API access has the same setting for final actions as every other connection, and it starts on Ask me. A script that sends a message, publishes a listing or deletes something gets 202 Accepted and waits for you to approve the action in Matchai. Write your scripts to handle both answers: final actions shows how.
Errors you may meet
| Status | Code or error type | What to do |
|---|---|---|
401 | authentication_error | The key is missing, mistyped or revoked. Create a new key. |
402 | insufficient_energy or energy_limit_reached | The account is out of Matchai Energy, or the connection reached its Energy limit. Nothing was done. |
403 | scope_missing | The key lacks a scope. The message names it. Create a key that has it. |
429 | rate_limited | Too many requests. Wait for Retry-After seconds. |
The errors page covers every code.