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

# Authentication

The G-Tateth API supports two authentication methods: API keys (recommended for server-to-server) and JWT tokens (for user-authenticated requests).

## API Key Authentication

API keys are the recommended method for server-to-server communication. They provide secure, long-lived access to the API.

### Creating an API Key

1. Log in to your G-Tateth account
2. Navigate to **Settings → Developer Console**
3. Click **"Create API Key"**
4. Choose your environment (Production or Staging)
5. Select permissions for the key
6. Copy your API key (it's only shown once!)

### Using Your API Key

Include your API key in the `Authorization` header:

```bash theme={null}
curl -H "Authorization: Bearer sk_live_your_api_key_here" \
  https://api.g-tateth.com/api/v1/conversations
```

Or use the `X-API-Key` header:

```bash theme={null}
curl -H "X-API-Key: sk_live_your_api_key_here" \
  https://api.g-tateth.com/api/v1/conversations
```

### API Key Types

* **Production keys** (`sk_live_...`) - Use in production environments
* **Test keys** (`sk_test_...`) - Use for development and testing

<Warning>
  Test keys are automatically blocked in production environments for safety.
</Warning>

### API Key Permissions

When creating an API key, select only the permissions it needs (principle of least privilege):

| Permission            | Grants access to                                         |
| --------------------- | -------------------------------------------------------- |
| `read:conversations`  | List and retrieve conversations                          |
| `write:conversations` | Create, update, and delete conversations                 |
| `read:customers`      | List and retrieve customer profiles                      |
| `write:customers`     | Create, update, and delete customer profiles             |
| `webhook:manage`      | Create, update, delete, test, and view logs for webhooks |
| `read:analytics`      | Access usage statistics and performance metrics          |

See the [API Keys reference](/api-reference/api-keys) for more details.

### API reference and Swagger UI

The interactive Swagger UI (requires JWT session) is at:

```text theme={null}
https://api.g-tateth.com/api-docs/
```

The raw OpenAPI spec (for Postman, code generators, and contract tests):

```text theme={null}
https://api.g-tateth.com/api-docs/spec.json
```

## JWT Authentication

JWT tokens can be used for user-authenticated requests. Obtain a JWT token through the authentication endpoints.

```bash theme={null}
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  https://api.g-tateth.com/api/v1/conversations
```

## Security Best Practices

1. **Never commit API keys to version control** - Use environment variables
2. **Rotate keys regularly** - Set up automatic rotation if possible
3. **Use test keys for development** - Keep production keys secure
4. **Limit permissions** - Only grant the minimum permissions needed
5. **Use IP whitelisting** - Restrict API key access to specific IPs
6. **Monitor usage** - Regularly check API key usage logs

## Error Responses

If authentication fails, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "success": false,
  "error": "Invalid or expired API key",
  "code": "API_KEY_INVALID"
}
```

Common error codes:

* `API_KEY_INVALID` - Invalid API key
* `API_KEY_EXPIRED` - API key has expired
* `API_KEY_INACTIVE` - API key is inactive
* `TENANT_SUSPENDED` - Tenant account is suspended