> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meetingkit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# auth.md

> How an AI agent gets MeetingKit API credentials on behalf of a user.

You are an agent that wants to call the MeetingKit API on a user's behalf. This file
tells you how to obtain credentials, what to ask the user to do, and how to handle the
credentials safely. It follows the [auth.md](https://workos.com/auth-md) convention.

Two hosts are relevant:

* **API** — `https://api.meetingkit.com/api/v1` — the API you will call. Reference:
  `https://docs.meetingkit.com`.
* **App** — `https://api.meetingkit.com` — where the user signs in.

## Use what is already configured first

Before you do anything credential-shaped, check whether the user has already wired
MeetingKit into your environment. Stop at the first one that exists:

1. `MEETINGKIT_API_KEY` in your process environment, or a project `.env` file the user
   has told you to read.
2. **MeetingKit MCP server** — if you are an MCP client (Claude, Cursor, Codex, etc.)
   and you only need to read or search the user's meetings and transcripts, connect
   `https://api.meetingkit.com/mcp`. Authentication is OAuth in the user's browser; you
   never see a key. Details: `https://docs.meetingkit.com/agents/mcp`.

If neither applies and you need the REST API, continue.

## Supported login option: user-assisted handoff

MeetingKit does not support unattended registration. The user signs in, or creates an
account, once in their browser and hands you a short-lived code. You exchange the code for
the user's API key. The whole handoff takes about a minute of the user's time.

### Step 1 — ask the user to open the handoff page

Give the user this link exactly:

```text theme={null}
https://api.meetingkit.com/app/agent_sessions/new
```

Tell them to:

1. Sign in, or create an account if they don't have one. The page returns to the handoff
   after signup.
2. Copy the code shown on the page and paste it back to you.

Do not open this page yourself. It needs the user's browser session, and automated
clients are challenged. Wait for the user to paste the code.

The code expires **5 minutes** after the page loads. Treat it as a secret while it is
valid: anyone holding it can run the exchange below. If it expired, ask the user to
reload the page for a fresh code.

### Step 2 — exchange the code for the API key

```http theme={null}
POST /api/v1/agent_sessions HTTP/1.1
Host: api.meetingkit.com
Content-Type: application/json

{ "token": "<code the user pasted>" }
```

No API key is needed for this call; the code is the credential. Reference:
`https://docs.meetingkit.com/api-reference/agent-sessions/exchange-a-handoff-code-for-credentials`.

A `200` response carries the credentials:

```json theme={null}
{
  "api_key": "<the user's personal API key>",
  "workspace_id": 123
}
```

Keep both:

* `api_key` is the user's own personal MeetingKit API key, the same one shown on
  their API settings page. It is not a platform or service credential. It does not
  expire on its own, and it acts as the user across every workspace they belong to.
* `workspace_id` is a workspace the user can write to. Most endpoints take
  `workspace_id`; use this one unless the user names another. List the rest with
  `GET /api/v1/workspaces`. Without a version header it is the workspace's integer id.

| Status | Meaning | What to do |
| - | - | - |
| `401` | The code is invalid or expired. | Ask the user to reload the handoff page and paste the new code. |
| `429` | Rate limited. | Wait a minute and retry the same code once, if it is still fresh. |

### Step 3 — use the key

Send the key bare in the `Authorization` header of every API request:

```http theme={null}
GET /api/v1/workspaces HTTP/1.1
Host: api.meetingkit.com
Authorization: <api_key>
```

Make that call first: a `200` listing the user's workspaces confirms the key works.
Then follow the API reference at `https://docs.meetingkit.com/api-reference/authentication`.

## Handle the key safely

* Put the key in `MEETINGKIT_API_KEY` in the user's `.env`, shell, or secret store, and
  read it from the environment at the moment of each call. If you cannot write to the
  user's project, keep it in a file only you can read and tell the user where it is;
  never paste it into the conversation.
* Never echo the key back to the user, print it in logs, or include it in commit
  messages, pull requests, error reports, or screenshots.
* Never interpolate the key inline in a shell command; reference the environment
  variable so it does not land in command history.
* Treat a `401` on a previously working key as revocation: drop it and ask the user to
  run the handoff again.

## Revocation

The user regenerates their key at `https://api.meetingkit.com/settings/personal/api`,
which invalidates the old one everywhere. You will discover this as a `401` on a
previously working request.

## What the account can do

A new account starts on the free plan with a personal workspace. Everything in the API
reference is available; paid features such as branded notetakers and multi-tenant
platforms are described at `https://docs.meetingkit.com/platform/tenancy`, and the
user upgrades from the app.