Connecting with Read-Only Access

Symptom#

You are trying to connect to your Upstash Redis database using a read-only token via a TCP client (such as redis-cli, ioredis, or redis-py), but you receive an authentication error similar to:

WRONGPASS invalid username-password pair or user is disabled

Diagnosis#

When you enable the Read-Only Token toggle in the Upstash Console, the TCP connection strings update the username from default to default_ro. This change can be easy to miss.

If you copied the read-only password but are still connecting with the default username (or omitting the username entirely), authentication will fail because the read-only password is associated with the default_ro user.

Solution 1: Use the default_ro Username#

The simplest approach is to use the built-in default_ro user. When you enable the Read-Only Token in the console, the connection strings automatically switch to use this user.

Make sure your connection includes both the default_ro username and the read-only password:

redis-cli:

redis-cli --tls -u rediss://default_ro:READ_ONLY_PASSWORD@YOUR_ENDPOINT:YOUR_PORT

Node.js (ioredis):

const Redis = require("ioredis");const client = new Redis("rediss://default_ro:READ_ONLY_PASSWORD@YOUR_ENDPOINT:YOUR_PORT");

Python (redis-py):

import redisr = redis.Redis(    host="YOUR_ENDPOINT",    port=YOUR_PORT,    username="default_ro",    password="READ_ONLY_PASSWORD",    ssl=True,)

Solution 2: Create a Custom Read-Only ACL User#

If you need more control over permissions, you can create a custom user with read-only access using Redis ACL.

1. Connect with your admin credentials:

redis-cli --tls -u rediss://default:YOUR_PASSWORD@YOUR_ENDPOINT:YOUR_PORT

2. Create a read-only user:

ACL SETUSER myreadonlyuser on >somesecurepassword ~* &* +@read -@dangerous

This command:

• on — enables the user
• >somesecurepassword — sets the password
• ~* — allows access to all keys
• &* — allows access to all pub/sub channels
• +@read — grants all read commands
• -@dangerous — revokes dangerous commands (such as KEYS, SCAN)

You can further restrict key access by replacing ~* with a pattern like ~cache:* to only allow reading keys that match that prefix.

3. Connect with the new user:

redis-cli --tls -u rediss://myreadonlyuser:somesecurepassword@YOUR_ENDPOINT:YOUR_PORT

If you want to use the REST API with your custom ACL user, you can generate a REST token for it. See REST Token for ACL Users for details.