> ## 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

> Authenticate API requests with a Personal Access Token or a Platform API Key

Every endpoint in this reference accepts two credential types in the same `Authorization` header. Which one you use determines who the API treats you as:

| Credential                      | Token format              | Acts as                                                                              | Plan                      |
| ------------------------------- | ------------------------- | ------------------------------------------------------------------------------------ | ------------------------- |
| **Personal Access Token (PAT)** | `rgo-...`                 | The token owner, with the owner's role and permissions                               | Essentials and above      |
| **Platform API Key**            | `ak_live:<uuid>:<secret>` | Any user in your company, chosen per request via the `x-meetergo-api-user-id` header | Enterprise / API Platform |

See [Authentication concepts](/developer-docs/authentication) for how the two credentials differ, and [Using a Personal Access Token](/developer-docs/personal-access-tokens) for the PAT guide.

## Personal Access Token

Create one at [my.meetergo.com/integrations](https://my.meetergo.com/integrations) (API card). A PAT behaves exactly like the user who created it: a regular member's PAT reaches that member's resources, while an admin's PAT can read and manage workspace-wide resources, such as listing users or retrieving appointments across the workspace.

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

<Warning>
  Do not send `x-meetergo-api-user-id` with a PAT. PATs always act as the token owner; if the header names another user, the request is rejected with `403`. User management endpoints (create, update, delete users) are not available to PATs.
</Warning>

## Platform API Key

Create one at [my.meetergo.com/admin/api-keys](https://my.meetergo.com/admin/api-keys) (Settings → API). Only company owners and admins can create and manage API keys.

<Steps>
  <Step title="Navigate to API Keys">
    Go to [my.meetergo.com/admin/api-keys](https://my.meetergo.com/admin/api-keys) in your dashboard.
  </Step>

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

  <Step title="Set expiration">
    Choose an expiration period between 1 and 90 days.
  </Step>

  <Step title="Copy your key">
    Copy the API key immediately—it won't be shown again.
  </Step>
</Steps>

<Warning>
  Credentials are shown only once when created. Store them securely in a password manager or secrets vault. You cannot retrieve them later.
</Warning>

### User context header

An API key is owned by your company, not by a user, so 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}
x-meetergo-api-user-id: 550e8400-e29b-41d4-a716-446655440000
```

The user must belong to your company. Endpoints marked accordingly (e.g. `POST /v4/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>

## Required headers

| Header                   | Required                            | Description                                 |
| ------------------------ | ----------------------------------- | ------------------------------------------- |
| `Authorization`          | Always                              | `Bearer <your-credential>` (PAT or API key) |
| `x-meetergo-api-user-id` | API key: most endpoints. PAT: never | UUID of the user to act on behalf of        |
| `Content-Type`           | For POST/PUT/PATCH                  | `application/json`                          |

## Verification request

Use this call to validate your credential and see who you are authenticated as:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.meetergo.com/v4/user/me" \
    -H "Authorization: Bearer <your-credential>"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.meetergo.com/v4/user/me', {
    headers: {
      'Authorization': 'Bearer <your-credential>'
    }
  });

  const user = await response.json();
  console.log('Authenticated as:', user);
  ```

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

  response = requests.get(
      'https://api.meetergo.com/v4/user/me',
      headers={
          'Authorization': 'Bearer <your-credential>'
      }
  )

  user = response.json()
  print(f"Authenticated as: {user}")
  ```
</CodeGroup>

A successful response (200 OK) returns the full user object: the token owner for a PAT, or the company owner for an API key without a user context header.

## Complete example

Request with all headers (Platform API Key):

<CodeGroup>
  ```bash cURL 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"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.meetergo.com/v4/meeting-type', {
    headers: {
      'Authorization': 'Bearer ak_live:uuid:secret',
      'x-meetergo-api-user-id': '550e8400-e29b-41d4-a716-446655440000'
    }
  });

  const meetingTypes = await response.json();
  ```

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

  response = requests.get(
      'https://api.meetergo.com/v4/meeting-type',
      headers={
          'Authorization': 'Bearer ak_live:uuid:secret',
          'x-meetergo-api-user-id': '550e8400-e29b-41d4-a716-446655440000'
      }
  )

  meeting_types = response.json()
  ```
</CodeGroup>

## Key lifecycle

### Expiration

API keys expire after the period you set (1-90 days maximum). PATs can optionally be given an expiration date. Plan to rotate credentials before they expire:

1. Create a new credential before the old one expires
2. Update your applications to use the new credential
3. The old credential will automatically stop working after expiration

### Deactivating and revoking

* **Personal Access Tokens:** revoke at [my.meetergo.com/integrations](https://my.meetergo.com/integrations).
* **Platform API Keys:** deactivate (temporary) or revoke (permanent) at [my.meetergo.com/admin/api-keys](https://my.meetergo.com/admin/api-keys).

If you suspect a credential has been compromised, revoke it, create a new one, and update your applications.

## Error responses

### Missing Authorization header

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

### Invalid API key

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

### Expired API key

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

### PAT with impersonation header

```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 your credentials in client-side code, public repositories, or logs.
</Warning>

### Do

* Store credentials in environment variables or a secrets manager
* Use different keys for development and production
* Rotate credentials regularly (before expiration)
* Monitor API usage for unexpected activity

### Don't

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