# API keys, OAuth apps and webhooks

> The three ways your code and MockFlow connect, what each one is for, and how they work together.

Source: https://mockflow.com/developers/concepts/keys-apps-and-webhooks

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 |
| --- | --- | --- |
| [API key](#api-keys) | A secret your code sends with each request. It acts as you, on the boards your account can open, with the [scopes](/developers/concepts/scopes) you chose. | Your own scripts, servers and internal tools work on your own workspace. |
| [OAuth app](#oauth-apps) | 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. |
| [Webhook](#webhooks) | 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](/developers/console/) with **Create key**, and send it on every request in an `Authorization: Bearer` header. The [Quickstart](/developers/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](/developers/concepts/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](/developers/console/?tab=oauth) 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:

1. Is sent to MockFlow, where they sign in and see your app's name and description.
2. Chooses **Authorize**, or **Deny**.
3. 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](/developers/concepts/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](/developers/console/?tab=webhooks), choose the [events](/developers/concepts/webhooks#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](/developers/concepts/webhooks#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](/developers/concepts/webhooks#callbackurl-hear-when-a-job-finishes) 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](/developers/what-you-can-build).