---
title: Authentication
description: Authenticate with the Syntext API using API keys.
icon: key
---

# Authentication

The Syntext API uses API keys for authentication. Each key is scoped to an organization and can have specific permissions.

## API Keys

### Creating an API Key

1. Go to [Syntext Dashboard](https://syntext.dev/dashboard)
2. Navigate to **Settings** → **API Keys**
3. Click **Create New Key**
4. Select permissions and expiration
5. Copy the key (shown only once)

### Key Format

API keys follow this format:

```
stx_abc12345_...xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

- `stx_abc12345_...` — Production key
- `sk_test_` — Test/sandbox key

## Using API Keys

Include your API key in the `Authorization` header:

```bash
curl https://api.syntext.dev/v1/projects \
  -H "Authorization: Bearer stx_abc12345_your_api_key"
```

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

## Key Permissions

API keys can be scoped to specific operations:

| Permission | Description |
|------------|-------------|
| `projects:read` | List and view projects |
| `projects:write` | Create and update projects |
| `builds:read` | View build status |
| `builds:write` | Trigger builds |
| `search:read` | Query search index |
| `admin` | Full access |

### Example: Read-Only Key

A CI system that only needs to trigger builds:

```json
{
  "name": "CI Deploy Key",
  "permissions": ["builds:write"]
}
```

## Key Rotation

Rotate keys periodically for security:

1. Create a new key with the same permissions
2. Update your applications to use the new key
3. Verify everything works
4. Delete the old key

## Environment Variables

Store API keys in environment variables:

```bash
export SYNTEXT_API_KEY=stx_abc12345_...
```

Then reference in code:

```typescript
import { Syntext } from '@syntext/sdk';

const client = new Syntext({
  apiKey: process.env.SYNTEXT_API_KEY
});
```

## API Key Endpoints

### List API Keys

```bash
curl https://api.syntext.dev/v1/api-keys \
  -H "Authorization: Bearer stx_abc12345_..."
```

```json
{
  "data": [
    {
      "id": "key_abc123",
      "name": "Production",
      "prefix": "stx_abc12345_...",
      "permissions": ["admin"],
      "created_at": "2024-01-15T12:00:00Z",
      "last_used_at": "2024-01-20T08:30:00Z"
    }
  ]
}
```

### Create API Key

```bash
curl -X POST https://api.syntext.dev/v1/api-keys \
  -H "Authorization: Bearer stx_abc12345_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI Deploy",
    "permissions": ["builds:write"]
  }'
```

```json
{
  "data": {
    "id": "key_def456",
    "name": "CI Deploy",
    "key": "stx_abc12345_...",
    "permissions": ["builds:write"],
    "created_at": "2024-01-21T10:00:00Z"
  }
}
```

<Note>
The full API key is only returned once, at creation time. Store it securely.
</Note>

### Delete API Key

```bash
curl -X DELETE https://api.syntext.dev/v1/api-keys/key_def456 \
  -H "Authorization: Bearer stx_abc12345_..."
```

## Security Best Practices

1. **Use environment variables** — Never hardcode keys
2. **Minimum permissions** — Grant only necessary access
3. **Rotate regularly** — Create new keys periodically
4. **Monitor usage** — Check `last_used_at` for anomalies
5. **Separate environments** — Use different keys for dev/staging/prod