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

# API Authentication

> How to authenticate with the Gately API

The Gately API uses API key authentication. Your API key contains the project context, so authentication is simple and straightforward.

## API Keys

API keys are used for all API communication. They provide full access to your project's data and automatically include the project context.

### Creating an API Key

1. Go to your Gately dashboard
2. Navigate to **Settings > API Keys**
3. Click **Create API Key**
4. Give your key a descriptive name
5. Copy and securely store the key (it won't be shown again)

### Using API Keys

Include the API key in the `Authorization` header:

```bash theme={null}
curl -X GET "https://api.usegately.com/api/v1/members" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

<Warning>
  Never expose API keys in client-side code. They should only be used in server-side applications.
</Warning>

### API Key Prefixes

| Prefix            | Environment      |
| ----------------- | ---------------- |
| `gately_sk_live_` | Production       |
| `gately_sk_test_` | Test/Development |

## JWT Tokens (Client-side)

JWT tokens are used for client-side authentication when users log in to your application.

### Obtaining a JWT Token

```javascript theme={null}
const { session } = await gately.login('user@example.com', 'password')
const token = session.access_token
```

### Using JWT Tokens

```bash theme={null}
curl -X GET "https://api.usegately.com/api/v1/user/profile" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
```

### Token Expiry

| Token Type    | Expiry |
| ------------- | ------ |
| Access Token  | 1 hour |
| Refresh Token | 7 days |

### Refreshing Tokens

```javascript theme={null}
const { session } = await gately.refreshSession()
```

Or via API:

```bash theme={null}
curl -X POST "https://api.usegately.com/api/v1/auth/refresh" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "your-refresh-token"}'
```

## Authentication Summary

| Method    | Authorization Header  | Use Case         |
| --------- | --------------------- | ---------------- |
| API Key   | `Bearer gately_xxxxx` | Server-to-server |
| JWT Token | `Bearer eyJhbG...`    | Client-side apps |

## Security Best Practices

<AccordionGroup>
  <Accordion title="Rotate API Keys Regularly">
    Create new API keys periodically and revoke old ones to minimize risk.
  </Accordion>

  <Accordion title="Use Environment Variables">
    Store API keys in environment variables, never in source code.
  </Accordion>

  <Accordion title="Limit Key Permissions">
    Create separate keys for different services with minimal required permissions.
  </Accordion>

  <Accordion title="Monitor Usage">
    Regularly review API key usage in your dashboard to detect anomalies.
  </Accordion>
</AccordionGroup>

## Error Responses

### Invalid Token

```json theme={null}
{
  "success": false,
  "error": "Invalid or expired token",
  "code": "INVALID_TOKEN"
}
```

### Missing Authentication

```json theme={null}
{
  "success": false,
  "error": "Authentication required",
  "code": "AUTH_REQUIRED"
}
```