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

# Authentication

> Secure your API requests with Bearer tokens

# Authentication

The Tella API uses Bearer token authentication. Every request must include your API key in the Authorization header.

## Getting your API key

1. Sign in to [Tella](https://www.tella.tv)
2. Navigate to **Settings** > **API Keys**
3. Click **Create key**
4. Copy and securely store your key

<Warning>
  API keys are shown only once when created. If you lose your key, you'll need
  to generate a new one.
</Warning>

## Using your API key

Include your API key in the `Authorization` header of every request:

```bash theme={null}
Authorization: Bearer tella_pk_xxxxx...
```

### Example request

```bash theme={null}
curl -H "Authorization: Bearer tella_pk_your_api_key" \
  https://api.tella.com/v1/videos
```

## API key format

Tella API keys follow this format:

```
tella_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

* Prefix: `tella_pk_` (identifies it as a Tella public API key)
* Suffix: 32 random alphanumeric characters

## Security best practices

<AccordionGroup>
  <Accordion title="Never expose your API key">
    * Don't commit API keys to version control
    * Don't include them in client-side code
    * Use environment variables to store keys
  </Accordion>

  <Accordion title="Use environment variables">
    ```bash theme={null}
    # Set the environment variable
    export TELLA_API_KEY="tella_pk_your_api_key"

    # Use it in your code
    curl -H "Authorization: Bearer $TELLA_API_KEY" \
      https://api.tella.com/v1/videos
    ```
  </Accordion>

  {" "}

  <Accordion title="Rotate keys regularly">
    Generate new API keys periodically and revoke old ones. This limits the impact
    if a key is compromised.
  </Accordion>

  <Accordion title="Use separate keys for different environments">
    Create separate API keys for development, staging, and production environments.
  </Accordion>
</AccordionGroup>

## Idempotent requests

A request that creates or changes something (`POST`, `PATCH`, `PUT`, `DELETE`) can be resent safely by sending an `Idempotency-Key` header: any string of at most 255 characters that is unique per API key, such as a UUID. If the first attempt completed but its response was lost (timeout, dropped connection), the resend returns the stored outcome instead of applying the change again.

```bash theme={null}
curl -X POST https://www.tella.tv/api/public/v1/videos/vid_abc123/clips \
  -H "Authorization: Bearer $TELLA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"sourceId": "src_xyz"}'
```

* The outcome is stored for 24 hours and replayed for an identical request (same method, path, query string and body).
* Reusing a key with a different request returns `400 bad_request`.
* Resending while the first attempt is still running returns `409 conflict`; retry after a moment.
* `429 rate_limited` and pre-execution `503 unavailable` outcomes are not stored, so those requests can be retried with the same key.
* A generic `500 server_error` is stored and replayed because the failure may have happened after the change was applied. Check whether it applied before trying again with a new key.
* If the key itself cannot be recorded, the request is not executed and answers `503 unavailable` with a `Retry-After` header; resend it unchanged.
* A key whose first attempt ended without recording an outcome (for example, the request was cut off) keeps returning `409 conflict` rather than running the request again. If a resend still answers `409` after a few minutes, check whether the change applied, then continue with a new key.

Requests without the header are never deduplicated. MCP tool calls use the same mechanism through `_meta.idempotencyKey`; see [MCP server](/docs/mcp-server#retrying-tool-calls-safely).

## Error responses

### 401 Unauthorized

Returned when the API key is missing or invalid:

```json theme={null}
{
  "error": "unauthorized",
  "description": "Invalid API key"
}
```

**Common causes:**

* Missing `Authorization` header
* Incorrect API key format
* Revoked or expired API key

### 403 Forbidden

Returned when the API key doesn't have permission for the requested resource:

```json theme={null}
{
  "error": "forbidden",
  "description": "Access denied to this resource"
}
```

### 409 Conflict

Returned when the request conflicts with the resource's current state, for example a resend whose first attempt under the same `Idempotency-Key` is still in progress:

```json theme={null}
{
  "error": "conflict",
  "message": "A request with this Idempotency-Key is still in progress"
}
```

### 503 Service Unavailable

Returned when a dependency refused before the request did anything, for example when an `Idempotency-Key` could not be recorded. Unlike a `500`, nothing was executed: resend the same request after the `Retry-After` delay.

```json theme={null}
{
  "error": "unavailable",
  "message": "The Idempotency-Key could not be recorded and the request was not executed; retry it"
}
```

### 404 Not Found

Returned when the API path doesn't exist:

```json theme={null}
{
  "error": "not_found",
  "message": "API endpoint not found",
  "resolution": "Use the OpenAPI description to find a supported path and method.",
  "docsUrl": "https://api.tella.com/openapi.json"
}
```

Use the [`docsUrl`](https://api.tella.com/openapi.json) value to find the supported endpoint and method.

## Revoking API keys

To revoke an API key:

1. Go to **Settings** > **API Keys**
2. Find the key you want to revoke
3. Click **Revoke**

Revoked keys immediately stop working for all requests.


## Related topics

- [Model Context Protocol (MCP)](/docs/mcp-server.md)
- [Tella MCP Server](/docs/help/integrations/mcp-server.md)
- [Create and manage API keys](/docs/help/integrations/api-keys.md)
- [Mac App](/docs/changelog/mac-app.md)
- [Quickstart](/docs/quickstart.md)