> ## 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.

# Configuration

> Configure the Gately SDK for your needs

## Initialization Options

```javascript theme={null}
import { GatelyClient } from '@gately/sdk'

const gately = new GatelyClient({
  // Required: Your API key
  apiKey: 'gately_pk_live_xxxxxxxx',
  
  // Optional configuration
  apiUrl: 'https://api.usegately.com',
  autoRefresh: true,
  suppressConsoleErrors: false
})
```

## Options Reference

### apiKey (Required)

Your Gately API key. Use public keys (`gately_pk_`) for browser apps and secret keys (`gately_sk_`) for server-side only.

```javascript theme={null}
const gately = new GatelyClient({
  apiKey: 'gately_pk_live_xxxxxxxx'
})
```

| Type     | Required |
| -------- | -------- |
| `string` | Yes      |

<Warning>
  Never expose secret API keys (`gately_sk_`) in client-side code. Use public keys for browser applications.
</Warning>

### apiUrl

The base URL for API requests. Only change this for self-hosted deployments.

```javascript theme={null}
const gately = new GatelyClient({
  apiKey: 'gately_pk_live_xxxxxxxx',
  apiUrl: 'https://your-custom-domain.com'
})
```

| Type     | Default                     |
| -------- | --------------------------- |
| `string` | `https://api.usegately.com` |

### autoRefresh

Automatically refresh the session before it expires.

```javascript theme={null}
const gately = new GatelyClient({
  apiKey: 'gately_pk_live_xxxxxxxx',
  autoRefresh: true // Enabled by default
})
```

| Type      | Default |
| --------- | ------- |
| `boolean` | `true`  |

When enabled, the SDK will:

* Monitor session expiry time
* Refresh the token 5 minutes before expiry
* Update stored session automatically

### suppressConsoleErrors

Suppress error messages in the browser console.

```javascript theme={null}
const gately = new GatelyClient({
  apiKey: 'gately_pk_live_xxxxxxxx',
  suppressConsoleErrors: true // Useful in production
})
```

| Type      | Default |
| --------- | ------- |
| `boolean` | `false` |

## React Provider Configuration

```jsx theme={null}
import { GatelyProvider } from '@gately/sdk'

function App() {
  return (
    <GatelyProvider 
      apiKey={process.env.NEXT_PUBLIC_GATELY_API_KEY}
      options={{
        autoRefresh: true,
        suppressConsoleErrors: process.env.NODE_ENV === 'production'
      }}
    >
      <YourApp />
    </GatelyProvider>
  )
}
```

## CDN Configuration

Configure via data attributes:

```html theme={null}
<script 
  src="https://cdn.usegately.com/gately.min.js" 
  data-api-key="YOUR_API_KEY"
  data-api-url="https://api.usegately.com"
  data-auto-refresh="true"
  data-auto-protect="true"
  defer
></script>
```

| Attribute           | Description                      |
| ------------------- | -------------------------------- |
| `data-api-key`      | Your API key (required)          |
| `data-api-url`      | Custom API URL                   |
| `data-auto-refresh` | Enable auto session refresh      |
| `data-auto-protect` | Enable automatic page protection |

## Environment-Based Configuration

```javascript theme={null}
const config = {
  development: {
    apiKey: process.env.GATELY_API_KEY_DEV,
    apiUrl: 'http://localhost:8787',
    suppressConsoleErrors: false
  },
  production: {
    apiKey: process.env.GATELY_API_KEY,
    apiUrl: 'https://api.usegately.com',
    suppressConsoleErrors: true
  }
}

const env = process.env.NODE_ENV || 'development'

const gately = new GatelyClient(config[env])
```

## Server-Side Configuration (Node.js)

For server-side applications, use your secret API key:

```javascript theme={null}
import { GatelyNodeClient } from '@gately/sdk/node'

const gately = new GatelyNodeClient({
  apiKey: process.env.GATELY_SECRET_KEY // gately_sk_live_xxxxxxxx
})
```

<Warning>
  Always use environment variables for secret keys. Never commit them to version control.
</Warning>

## Session Storage

By default, sessions are stored in `localStorage`. The SDK also sets cookies for cross-origin compatibility:

| Cookie              | Purpose          |
| ------------------- | ---------------- |
| `gately_auth_token` | JWT access token |
| `gately_session`    | Session data     |

## Debugging

Enable verbose logging for debugging:

```javascript theme={null}
// In browser console
localStorage.setItem('gately_debug', 'true')

// Then reload the page
location.reload()
```

This will log:

* API requests and responses
* Session management events
* Page protection checks
* OAuth flow details

To disable:

```javascript theme={null}
localStorage.removeItem('gately_debug')
location.reload()
```