API keys, OAuth apps and webhooks
The three ways your code and MockFlow connect, what each one is for, and how they work together.
There are three ways to connect your code with MockFlow, and each one has a single job. An API key and an OAuth app are how your code talks to MockFlow: they let it call the API. A webhook is how MockFlow talks to your code: it tells your server when something happens.
At a glance
What it is | Use it when | |
|---|---|---|
A secret your code sends with each request. It acts as you, on the boards your account can open, with the scopes you chose. | Your own scripts, servers and internal tools work on your own workspace. | |
An app you register once. Each person who connects it signs in to MockFlow and approves it, and your app gets a token for their account. | Other people connect their own MockFlow accounts to your product. | |
An address on your server that MockFlow calls when something happens. It only tells you; it does not change anything. | You want to hear when boards are created, shared or trashed, or when a job finishes, without asking again and again. |
API keys
An API key is the quickest way to start. Create one on the API keys tab of the developer console with Create key, and send it on every request in an Authorization: Bearer header. The Quickstart walks through it.
When you create a key you choose:
Scopes: what the key may do, such as read boards or create them. Give a key only the scopes it needs.
Expires: never, or after 30 days, 90 days or a year.
IP allow list: optionally, the only addresses the key works from.
Belongs to: a workspace owner can also make a key that belongs to the workspace rather than to them. It keeps working after the person who made it leaves.
The key is shown once, when it is created; MockFlow keeps only a hash of it. Keep it on your server and out of code that runs in a browser or an app people download. Anyone who has the key can do what it allows, as you.
Use an API key for: a script that builds a weekly report board, an internal tool for your team, or a server that keeps your own workspace in step with another system.
OAuth apps
An OAuth app lets your product work in other people's MockFlow accounts, with their permission. Register it on the OAuth apps tab of the developer console with Register an app, and you get a client ID, plus a client secret for an app with a server.
Each person who connects your app:
Is sent to MockFlow, where they sign in and see your app's name and description.
Chooses Authorize, or Deny.
Is sent back to your app, which exchanges a one time code for a token.
Your app then calls the API with that token exactly as it would with a key, and works on that person's boards with the scopes they approved. A new app is in development: only you and people in your workspace can connect it. Publish it from the console when it is ready for everyone.
Use an OAuth app for: a product your customers connect, such as a planning tool that creates boards in each customer's own account. The OAuth apps page has the full flow.
Webhooks
A webhook is an https address on your server. Add one on the Webhooks tab of the developer console, choose the events you want, and MockFlow sends a signed POST there each time one happens:
a board is created, renamed, locked, moved, trashed or restored
someone gains or loses access to a space or a board
a job you started through the API finishes or fails
Webhooks do not fire for each edit to the items on a board. Each request is signed, and your server should check the signature before trusting it. If your server is down, MockFlow retries for a day.
A webhook only reports on boards the person who set it up can open. For one job you start, such as a Mida generation, you can instead pass a callbackUrl with the request and hear about that job alone.
Use a webhook for: adding each new board to your project tracker, posting to your team channel when a board is shared, or carrying on once a generation is done.
How they work together
Most integrations use a key or an OAuth app to call the API, and add a webhook or a callbackUrl when they need to hear back. For example:
An internal report: an API key only. A script creates a board each Monday and fills it with charts.
A wall of the team's new boards: an API key and a webhook. The webhook says a board was created, and the key reads its outline and exports a picture of it for the wall.
A product for your customers: an OAuth app and a callbackUrl. Each customer connects their account, your app asks Mida to build a board with their token, and the callbackUrl tells your server when it is ready to show them.
To see what these make possible, read What you can build.