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

# @atxp/redis

> Redis OAuth database implementation for scalable authentication and session management in ATXP applications

## Overview

The [@atxp/redis](https://www.npmjs.com/package/@atxp/redis) package provides a Redis-based OAuth database implementation for the Authorization Token Exchange Protocol (ATXP). It offers distributed OAuth token storage using Redis, designed for scalable applications that need shared token storage across multiple server instances or require high-performance, in-memory token caching.

<Info>
  This package is designed to work seamlessly with `@atxp/client` and `@atxp/express` packages when you need distributed storage that can be shared across multiple application instances. For single-instance applications, consider using [@atxp/sqlite](/developers/api-reference/sqlite) instead.
</Info>

## Installation

```bash theme={null}
npm install @atxp/redis
```

<Note>
  The `@atxp/redis` package includes TypeScript definitions and requires Node.js 16 or higher. It automatically installs `@atxp/common` as a dependency and requires a Redis server to be running.
</Note>

## API Reference

### Classes

#### `RedisOAuthDatabase`

The main class for managing OAuth tokens in a Redis database.

```typescript theme={null}
import { RedisOAuthDatabase } from '@atxp/redis'
```

**Constructor**

```typescript theme={null}
new RedisOAuthDatabase(options: RedisOAuthDatabaseOptions)
```

<ParamField body="options" type="RedisOAuthDatabaseOptions" required>
  Configuration options for the Redis database connection.

  <Expandable title="RedisOAuthDatabaseOptions properties">
    <ParamField body="url" type="string" required>
      Redis connection URL. Format: `redis://[username:password@]host[:port][/database]`
    </ParamField>

    <ParamField body="host" type="string" optional>
      Redis server hostname. Defaults to 'localhost' if not provided in URL.
    </ParamField>

    <ParamField body="port" type="number" optional>
      Redis server port. Defaults to 6379 if not provided in URL.
    </ParamField>

    <ParamField body="password" type="string" optional>
      Redis server password for authentication.
    </ParamField>

    <ParamField body="db" type="number" optional>
      Redis database number (0-15). Defaults to 0.
    </ParamField>

    <ParamField body="keyPrefix" type="string" optional>
      Prefix for all Redis keys. Defaults to 'atxp:oauth:'.
    </ParamField>

    <ParamField body="connectionTimeout" type="number" optional>
      Connection timeout in milliseconds. Defaults to 10000.
    </ParamField>

    <ParamField body="retryDelayOnFailover" type="number" optional>
      Delay between retry attempts in milliseconds. Defaults to 100.
    </ParamField>

    <ParamField body="maxRetriesPerRequest" type="number" optional>
      Maximum number of retry attempts per request. Defaults to 3.
    </ParamField>
  </Expandable>
</ParamField>

**Methods**

<ResponseField name="storeToken" type="Promise<void>">
  Stores an OAuth token in Redis with optional expiration.

  <ParamField body="key" type="string" required>
    Unique identifier for the token.
  </ParamField>

  <ParamField body="token" type="string" required>
    The OAuth token value to store.
  </ParamField>

  <ParamField body="expiresAt" type="Date" optional>
    Optional expiration date for the token. If provided, Redis will automatically expire the key.
  </ParamField>
</ResponseField>

<ResponseField name="getToken" type="Promise<string | null>">
  Retrieves an OAuth token from Redis.

  <ParamField body="key" type="string" required>
    Unique identifier for the token to retrieve.
  </ParamField>
</ResponseField>

<ResponseField name="deleteToken" type="Promise<boolean>">
  Deletes an OAuth token from Redis.

  <ParamField body="key" type="string" required>
    Unique identifier for the token to delete.
  </ParamField>
</ResponseField>

<ResponseField name="hasToken" type="Promise<boolean>">
  Checks if a token exists in Redis.

  <ParamField body="key" type="string" required>
    Unique identifier for the token to check.
  </ParamField>
</ResponseField>

<ResponseField name="listTokens" type="Promise<string[]>">
  Lists all token keys stored in Redis with the configured prefix.
</ResponseField>

<ResponseField name="close" type="Promise<void>">
  Closes the Redis connection and releases resources.
</ResponseField>

### Interfaces

#### `RedisOAuthDatabaseOptions`

Configuration options for the Redis OAuth database.

```typescript theme={null}
interface RedisOAuthDatabaseOptions {
  url?: string
  host?: string
  port?: number
  password?: string
  db?: number
  keyPrefix?: string
  connectionTimeout?: number
  retryDelayOnFailover?: number
  maxRetriesPerRequest?: number
}
```

<ResponseField name="url" type="string" optional>
  Complete Redis connection URL. Takes precedence over individual host/port/password/db options.
</ResponseField>

<ResponseField name="host" type="string" optional>
  Redis server hostname. Defaults to 'localhost'.
</ResponseField>

<ResponseField name="port" type="number" optional>
  Redis server port. Defaults to 6379.
</ResponseField>

<ResponseField name="password" type="string" optional>
  Redis server password for authentication.
</ResponseField>

<ResponseField name="db" type="number" optional>
  Redis database number (0-15). Defaults to 0.
</ResponseField>

<ResponseField name="keyPrefix" type="string" optional>
  Prefix for all Redis keys to avoid conflicts. Defaults to 'atxp:oauth:'.
</ResponseField>

<ResponseField name="connectionTimeout" type="number" optional>
  Connection timeout in milliseconds. Defaults to 10000.
</ResponseField>

<ResponseField name="retryDelayOnFailover" type="number" optional>
  Delay between retry attempts in milliseconds. Defaults to 100.
</ResponseField>

<ResponseField name="maxRetriesPerRequest" type="number" optional>
  Maximum number of retry attempts per request. Defaults to 3.
</ResponseField>

## Usage Examples

### Basic Setup

Create a Redis OAuth database instance:

```typescript theme={null}
import { RedisOAuthDatabase } from '@atxp/redis'

// Initialize the database with connection URL
const oauthDb = new RedisOAuthDatabase({
  url: 'redis://localhost:6379'
})

// Store a token with expiration
await oauthDb.storeToken('user_123', 'oauth_token_value', new Date(Date.now() + 3600000))

// Retrieve a token
const token = await oauthDb.getToken('user_123')
console.log('Token:', token)

// Check if token exists
const hasToken = await oauthDb.hasToken('user_123')
console.log('Has token:', hasToken)

// List all tokens
const allTokens = await oauthDb.listTokens()
console.log('All tokens:', allTokens)

// Clean up
await oauthDb.close()
```

### Advanced Configuration

Configure Redis with authentication and custom settings:

```typescript theme={null}
import { RedisOAuthDatabase } from '@atxp/redis'

const oauthDb = new RedisOAuthDatabase({
  host: 'redis.example.com',
  port: 6380,
  password: 'your_redis_password',
  db: 1,
  keyPrefix: 'myapp:oauth:',
  connectionTimeout: 15000,
  maxRetriesPerRequest: 5
})
```

### Integration with ATXP Client

Use Redis storage with the ATXP client for distributed token management:

```typescript theme={null}
import { atxpClient, ATXPAccount } from '@atxp/client'
import { RedisOAuthDatabase } from '@atxp/redis'

// Create Redis OAuth database
const oauthDb = new RedisOAuthDatabase({
  url: process.env.REDIS_URL || 'redis://localhost:6379'
})

// Create ATXP client with Redis OAuth storage
const client = await atxpClient({
  mcpServer: 'https://search.mcp.atxp.ai/',
  account: new ATXPAccount(process.env.ATXP_CONNECTION),
  oauthDatabase: oauthDb
})

// Use the client - tokens will be automatically stored in Redis
const result = await client.callTool('search_search', {
  query: 'example query'
})
```

### Integration with ATXP Server

Use Redis storage with the ATXP server for distributed session management:

```typescript theme={null}
import { atxpExpress, ATXPAccount } from '@atxp/express'
import { RedisOAuthDatabase } from '@atxp/redis'
import express from 'express'

// Create Redis OAuth database
const oauthDb = new RedisOAuthDatabase({
  url: process.env.REDIS_URL || 'redis://localhost:6379',
  keyPrefix: 'server:oauth:'
})

const app = express()

// Use ATXP server with Redis OAuth storage
app.use('/mcp', atxpExpress({
  destination: new ATXPAccount(process.env.ATXP_CONNECTION),
  payeeName: 'My MCP Server',
  oauthDatabase: oauthDb
}))

app.listen(3000, () => {
  console.log('Server running on port 3000')
})
```

## Configuration

### Connection Options

Redis supports multiple connection methods:

```typescript theme={null}
// Using connection URL (recommended)
const oauthDb = new RedisOAuthDatabase({
  url: 'redis://username:password@host:port/database'
})

// Using individual options
const oauthDb = new RedisOAuthDatabase({
  host: 'localhost',
  port: 6379,
  password: 'password',
  db: 0
})

// Using Redis Cloud or other hosted services
const oauthDb = new RedisOAuthDatabase({
  url: 'rediss://username:password@host:port' // Note: rediss:// for SSL
})
```

### Environment Variables

Configure Redis connection using environment variables:

```bash theme={null}
# .env file
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=your_password
REDIS_DB=0
REDIS_KEY_PREFIX=atxp:oauth:
```

```typescript theme={null}
import { RedisOAuthDatabase } from '@atxp/redis'

const oauthDb = new RedisOAuthDatabase({
  url: process.env.REDIS_URL,
  password: process.env.REDIS_PASSWORD,
  db: parseInt(process.env.REDIS_DB || '0'),
  keyPrefix: process.env.REDIS_KEY_PREFIX || 'atxp:oauth:'
})
```

### Key Management

Redis keys are automatically prefixed to avoid conflicts:

```typescript theme={null}
// With default prefix 'atxp:oauth:'
await oauthDb.storeToken('user_123', 'token_value')
// Stored as: atxp:oauth:user_123

// With custom prefix
const oauthDb = new RedisOAuthDatabase({
  url: 'redis://localhost:6379',
  keyPrefix: 'myapp:auth:'
})
await oauthDb.storeToken('user_123', 'token_value')
// Stored as: myapp:auth:user_123
```

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="Connection refused errors">
    If you encounter connection refused errors:

    * Ensure Redis server is running
    * Check if the host and port are correct
    * Verify firewall settings allow Redis connections
    * Test connection with redis-cli

    ```bash theme={null}
    # Test Redis connection
    redis-cli -h localhost -p 6379 ping
    ```

    ```typescript theme={null}
    // Increase connection timeout
    const oauthDb = new RedisOAuthDatabase({
      url: 'redis://localhost:6379',
      connectionTimeout: 30000
    })
    ```
  </Accordion>

  <Accordion title="Authentication failures">
    If you're experiencing authentication failures:

    * Verify the password is correct
    * Check if Redis requires authentication
    * Ensure the username format is correct for Redis 6+

    ```typescript theme={null}
    // Use proper authentication format
    const oauthDb = new RedisOAuthDatabase({
      url: 'redis://username:password@localhost:6379'
    })
    ```
  </Accordion>

  <Accordion title="Memory issues with large token sets">
    For applications with many tokens:

    * Monitor Redis memory usage
    * Configure appropriate eviction policies
    * Consider token cleanup for expired entries
    * Use Redis clustering for horizontal scaling

    ```typescript theme={null}
    // Implement token cleanup
    const allTokens = await oauthDb.listTokens()
    for (const key of allTokens) {
      const token = await oauthDb.getToken(key)
      // Check if token is expired and delete if necessary
    }
    ```
  </Accordion>

  <Accordion title="Network timeouts">
    If you're experiencing network timeouts:

    * Increase connection timeout values
    * Check network stability between application and Redis
    * Consider using connection pooling
    * Monitor Redis server performance

    ```typescript theme={null}
    const oauthDb = new RedisOAuthDatabase({
      url: 'redis://localhost:6379',
      connectionTimeout: 30000,
      retryDelayOnFailover: 200,
      maxRetriesPerRequest: 5
    })
    ```
  </Accordion>
</AccordionGroup>

### Performance Considerations

<Tip>
  For optimal Redis performance:

  * Use Redis clustering for high availability and horizontal scaling
  * Configure appropriate memory eviction policies
  * Monitor Redis memory usage and implement cleanup strategies
  * Use connection pooling for high-concurrency applications
  * Consider Redis persistence settings based on your requirements
</Tip>

### Migration from Other Storage

If you're migrating from another OAuth storage solution:

1. Export tokens from your current system
2. Set up Redis server
3. Import tokens using the `storeToken` method
4. Update your application to use the Redis database

```typescript theme={null}
// Example migration script
import { RedisOAuthDatabase } from '@atxp/redis'

const oauthDb = new RedisOAuthDatabase({
  url: 'redis://localhost:6379'
})

// Import tokens from your existing system
const existingTokens = await getTokensFromOldSystem()
for (const token of existingTokens) {
  await oauthDb.storeToken(token.key, token.value, token.expiresAt)
}
```

## Related Packages

<CardGroup cols={2}>
  <Card title="@atxp/client" icon="laptop" href="/developers/api-reference/client">
    Client-side integration for MCP clients with OAuth authentication.
  </Card>

  <Card title="@atxp/express" icon="server" href="/developers/api-reference/express">
    Server-side middleware for MCP servers with payment processing.
  </Card>

  <Card title="@atxp/sqlite" icon="database" href="/developers/api-reference/sqlite">
    SQLite OAuth database for single-instance applications.
  </Card>

  <Card title="@atxp/common" icon="code" href="/developers/api-reference/common">
    Shared utilities and types used across ATXP packages.
  </Card>
</CardGroup>