> For the documentation index, fetch https://sync.so/docs/llms.txt. Append .md to a page URL for Markdown. Documentation-search MCP: https://sync.so/docs/_mcp/server.

# Authentication

> Learn how to authenticate with the sync. labs lip sync API using API keys. Setup guide, security best practices, and code examples.

Sync Labs uses API key authentication via the `x-api-key` header. Create an API key from the [API Keys](https://sync.so/settings/api-keys) page, then include it in every request.

```bash
x-api-key: your-api-key
```

## Create an API Key

1. Open the [API Keys](https://sync.so/settings/api-keys) page.
2. Optional: Enter a name for the key, such as `production` or `staging`. The name helps you tell keys apart, and it appears in the API Key column of usage exports. If you leave it blank, the key is named `API key`.
3. Select **Create new key**.
4. Copy the key from the dialog and store it securely. The full key is shown only once.

## Rename or Revoke an API Key

Organization members see and manage only the keys they created. Organization admins and owners see every key in the organization and can rename or revoke any of them.

* **Rename a key:** On the [API Keys](https://sync.so/settings/api-keys) page, select **Edit key** in the key's row, enter the new name, then select **Save key**.
* **Revoke a key:** Select **Revoke** in the key's row, then select **Confirm**. Revoking is permanent and immediately stops any service or application that uses the key.

## Sample Request

You can run the following sample request to generate a lipsynced video rightaway. Be sure to replace `<apiKey>` with your actual API key.

```bash
curl -X POST https://api.sync.so/v2/generate \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "model": "lipsync-2",
  "input": [
    {
      "type": "video",
      "url": "https://assets.sync.so/docs/example-video.mp4"
    },
    {
      "type": "audio",
      "url": "https://assets.sync.so/docs/example-audio.wav"
    }
  ],
  "outputFileName": "my_custom_output"
}'
```

## SDK Authentication

The official Python and TypeScript SDKs automatically read your API key from the `SYNC_API_KEY` environment variable. Set the variable once and the SDK handles lip sync API authentication for every request.

```bash
export SYNC_API_KEY="your-api-key"
```

No additional configuration is needed. The SDK picks up the key at initialization:

#### Python

```python
from sync import Sync

# Reads SYNC_API_KEY from the environment automatically
sync = Sync()
```

You can also pass the key directly:

```python
sync = Sync(api_key="your-api-key")
```

#### TypeScript

```typescript
import { SyncClient } from "@sync.so/sdk";

// Reads SYNC_API_KEY from the environment automatically
const sync = new SyncClient();
```

You can also pass the key directly:

```typescript
const sync = new SyncClient({ apiKey: "your-api-key" });
```

## API Key Security Best Practices

Your API key grants full access to the Sync Labs API on your behalf. Treat it like a password.

* **Never commit keys to source control.** Add `.env` to your `.gitignore` and use a secrets manager or environment variables instead.
* **Use environment variables in production.** Store `SYNC_API_KEY` in your hosting platform's secrets or environment config rather than hardcoding it.
* **Rotate keys regularly.** Generate a new key from the [API Keys](https://sync.so/settings/api-keys) page periodically, then revoke the old one.
* **Use separate keys per environment.** Create distinct keys for development, staging, and production, and name each one after its environment. A compromised dev key then does not affect production traffic, and you can tell the keys apart when you revoke one or review usage.
* **Restrict access.** Only share your API key with team members and services that need it.

## Error Handling

If a request is missing a valid API key, the Sync Labs API returns a **401 Unauthorized** response.

Common causes:

* **Missing header** -- The `x-api-key` header was not included in the request.
* **Invalid key** -- The key is misspelled, expired, or revoked.
* **Wrong environment variable** -- The `SYNC_API_KEY` environment variable is not set or points to the wrong key.

When you receive a 401, verify that:

1. Your API key is copied correctly with no extra whitespace.
2. The `x-api-key` header (not `Authorization`) is present in the request.
3. The key is still active on the [API Keys](https://sync.so/settings/api-keys) page.

For a full list of error codes and resolution steps, see the [Error Handling](/developer-guides/error-handling) guide.

## Authentication Reference

* **Auth header:** `x-api-key: YOUR_KEY`
* **Environment variable:** `SYNC_API_KEY`
* **Base URL:** `https://api.sync.so/v2`
* **API key management:** [https://sync.so/settings/api-keys](https://sync.so/settings/api-keys)
* **API key name:** Optional at creation; a blank name defaults to `API key`
* **API key permissions:** Members can rename and revoke keys they created; admins and owners can rename and revoke every key in the organization

### SDK Authentication

| SDK        | Install               | Auto-reads env var   |
| ---------- | --------------------- | -------------------- |
| Python     | `pip install syncsdk` | Yes (`SYNC_API_KEY`) |
| TypeScript | `npm i @sync.so/sdk`  | Yes (`SYNC_API_KEY`) |

### Direct Key Passing

* Python: `Sync(api_key="your-api-key")`
* TypeScript: `new SyncClient({ apiKey: "your-api-key" })`

### Auth Error

* Missing or invalid API key returns **401 Unauthorized**
* Use `x-api-key` header (not `Authorization`)