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

# Authentication

> Personal Access Tokens and Platform API Keys: who each credential acts as

All API requests authenticate with a Bearer token in the `Authorization` header. meetergo has two credential types. They use the same header, but they represent different principals. The important question is not which data a credential can touch, but **who the API treats you as**.

## The two credentials

<CardGroup cols={2}>
  <Card title="Personal Access Token" icon="user">
    **Essentials plan and above**

    Authenticates as **you**. Every call behaves exactly as if you performed the action in the dashboard, with your role and permissions.
  </Card>

  <Card title="Platform API Key" icon="building">
    **Enterprise / API Platform**

    A company-owned credential for building applications on meetergo. Acts on behalf of **any user in your company** and manages platform users.
  </Card>
</CardGroup>

You can tell them apart by their prefix:

| Credential            | Token format              | Created at                                                 |
| --------------------- | ------------------------- | ---------------------------------------------------------- |
| Personal Access Token | `rgo-...`                 | [Integrations → API](https://my.meetergo.com/integrations) |
| Platform API Key      | `ak_live:<uuid>:<secret>` | [Settings → API](https://my.meetergo.com/admin/api-keys)   |

## Personal Access Token

A Personal Access Token (PAT) authenticates as the user who created it and **inherits that user's permissions**. It is not limited to the owner's own data; what a PAT can do is exactly what its owner can do:

* A regular member's PAT manages that member's meeting types, availability, and bookings.
* An **admin's PAT** can read and manage workspace-wide resources. For example, it can list the company's users or retrieve appointments across the whole workspace by filtering on `userId`.

A few things a PAT can never do, regardless of the owner's role:

* **Act on behalf of another user.** The `x-meetergo-api-user-id` header is a Platform API Key feature. A PAT request carrying that header for another user is rejected with `403`.
* **Manage the user lifecycle.** Creating, deleting, or updating users requires a Platform API Key (or the dashboard).
* **Create or manage credentials** (other PATs, API keys) or trigger GDPR exports.

<Info>
  Building an organization-level integration? Create the PAT from a stable company admin account (for example `integrations@yourcompany.com`) rather than a personal employee account. If the token's owner is removed from the workspace, the token stops working.
</Info>

**Best for:** Zapier and workflow automation, CRM syncing, retrieving workspace data with an admin token, single-user integrations.

See [Using a Personal Access Token](/developer-docs/personal-access-tokens) for a hands-on guide.

### Creating a Personal Access Token

<Steps>
  <Step title="Navigate to Integrations">
    Go to [my.meetergo.com/integrations](https://my.meetergo.com/integrations) and find the **API** card
  </Step>

  <Step title="Create a new token">
    Click **Connect** and give it a descriptive name (e.g., "Zapier", "CRM Sync")
  </Step>

  <Step title="Set expiration">
    Optionally choose an expiration period.
  </Step>

  <Step title="Copy immediately">
    The token is shown only once. Store it securely.
  </Step>
</Steps>

### Example request

A PAT needs no extra headers. This request lists meeting types visible to the token owner:

```bash theme={null}
curl -X GET "https://api.meetergo.com/v4/meeting-type" \
  -H "Authorization: Bearer rgo-your-token"
```

## Platform API Key

A Platform API Key is owned by your **company**, not by an individual user. It is designed for applications that programmatically manage users and their scheduling: marketplaces, white-label integrations, telehealth or coaching platforms, recruitment software.

**Capabilities:**

* Create, update, and delete platform users programmatically
* Act on behalf of any user in your company via the `x-meetergo-api-user-id` header
* Access availability, bookings, and meeting types across the organization
* Manage webhooks and real-time events

**Where to get it:** [Settings → API](https://my.meetergo.com/admin/api-keys) (Enterprise plan or API Platform access). Only company owners and admins can create and manage API keys.

<Info>
  Need Platform API access? [Book a demo](https://cal.meetergo.com/team/sales/democall) to discuss your integration requirements. The API Platform plan is priced per booking and includes platform user types that do not count as workspace seats.
</Info>

### Creating a Platform API Key

<Steps>
  <Step title="Navigate to API Settings">
    Go to [my.meetergo.com/admin/api-keys](https://my.meetergo.com/admin/api-keys) (Settings → API tab)
  </Step>

  <Step title="Create a new key">
    Click **Create API Key** and give it a descriptive name (e.g., "Production", "Staging")
  </Step>

  <Step title="Set expiration">
    Choose 1-90 days. Keys expire automatically for security.
  </Step>

  <Step title="Copy immediately">
    The key is shown only once. Store it securely.
  </Step>
</Steps>

### The user context header

Because an API key is not a user, most endpoints need to know which user to act as. Pass that user's ID in the `x-meetergo-api-user-id` header:

```bash theme={null}
curl -X GET "https://api.meetergo.com/v4/meeting-type" \
  -H "Authorization: Bearer ak_live:uuid:secret" \
  -H "x-meetergo-api-user-id: 550e8400-e29b-41d4-a716-446655440000"
```

The user must belong to your company. Some endpoints (e.g. creating a platform user, `GET /v4/user/me`) work without the header and then act as the company owner.

<Info>
  Get a user's ID from `GET /v4/user` (list users), from the `userId` returned when creating a user, or from `GET /v4/user/me`.
</Info>

## Capability comparison

|                                 | Personal Access Token                                               | Platform API Key                      |
| ------------------------------- | ------------------------------------------------------------------- | ------------------------------------- |
| Acts as                         | The token owner                                                     | Any user in your company (via header) |
| Permissions                     | The owner's role. An admin's PAT reaches workspace-wide data        | Full access to company resources      |
| Create / delete users           | ❌                                                                   | ✅                                     |
| Update other users' profiles    | ❌                                                                   | ✅                                     |
| `x-meetergo-api-user-id` header | Rejected if it names another user                                   | Required on most endpoints            |
| Owned by                        | An individual user. Stops working if that user leaves the workspace | The company                           |
| Plan                            | Essentials and above                                                | Enterprise / API Platform             |

## Required headers

| Header                   | PAT                           | Platform API Key | Description                          |
| ------------------------ | ----------------------------- | ---------------- | ------------------------------------ |
| `Authorization`          | Yes                           | Yes              | `Bearer <your-token>`                |
| `x-meetergo-api-user-id` | No (rejected for other users) | Most endpoints   | UUID of the user to act on behalf of |
| `Content-Type`           | POST/PUT/PATCH                | POST/PUT/PATCH   | `application/json`                   |

## Key management

### Rotation

Both credential types support expiration. Plan rotation before a credential expires:

1. Create a new token or key before the old one expires
2. Update your application to use the new credential
3. The old credential stops working after expiration

<Tip>
  Set calendar reminders to rotate credentials before expiration.
</Tip>

### Deactivating and revoking

* **Personal Access Tokens:** revoke at [my.meetergo.com/integrations](https://my.meetergo.com/integrations) via the **Revoke** button.
* **Platform API Keys:** deactivate (temporarily) or revoke (permanently) at [my.meetergo.com/admin/api-keys](https://my.meetergo.com/admin/api-keys).

If a credential is compromised, revoke it immediately, create a new one, and update your application.

## Error responses

### Missing Authorization header

```json theme={null}
{
  "statusCode": 401,
  "message": "Missing authorization header",
  "error": "Unauthorized"
}
```

### Invalid or expired credential

```json theme={null}
{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}
```

### PAT with impersonation header

Returned when a Personal Access Token sends `x-meetergo-api-user-id` for another user:

```json theme={null}
{
  "statusCode": 403,
  "message": "The 'x-meetergo-api-user-id' header requires a Platform API Key. Personal Access Tokens always act as the token owner and cannot act on behalf of other users.",
  "error": "Forbidden"
}
```

### Missing user header (API key)

```json theme={null}
{
  "statusCode": 400,
  "message": "Missing required header 'x-meetergo-api-user-id' for API key authentication",
  "error": "Bad Request"
}
```

### Acting user not in your company (API key)

```json theme={null}
{
  "statusCode": 500,
  "message": "API user does not belong to company",
  "error": "Internal Server Error"
}
```

## Security best practices

<Warning>
  Never expose tokens or API keys in client-side code, public repositories, or logs.
</Warning>

### Do

* Store credentials in environment variables or secrets managers
* Use different keys for development and production
* Rotate credentials regularly
* Monitor API usage for unexpected activity
* Use HTTPS for all requests (enforced by our API)

### Don't

* Commit credentials to version control
* Share credentials via email, chat, or insecure channels
* Log credentials in application logs
* Use the same credential across unrelated applications
* Store credentials in frontend JavaScript

## Environment variable example

```bash theme={null}
# .env (never commit this file)
MEETERGO_API_KEY=ak_live:01234567-89ab-cdef-1234-567890abcdef:secretpart123
```

```javascript theme={null}
// Node.js
const apiKey = process.env.MEETERGO_API_KEY;

const response = await fetch('https://api.meetergo.com/v4/user/me', {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});
```

```python theme={null}
# Python
import os
import requests

api_key = os.environ['MEETERGO_API_KEY']

response = requests.get(
    'https://api.meetergo.com/v4/user/me',
    headers={'Authorization': f'Bearer {api_key}'}
)
```