Development Tokens

Generate temporary development tokens for testing PowerSync authentication without a full auth provider.

PowerSync allows generating temporary development tokens for authentication.

This is useful for developers who want to get up and running quickly, without full auth integration.

This can also be used to generate a token for a specific user to debug issues.

Generating a Development Token

PowerSync Cloud

1. In the PowerSync Dashboard, select your project and instance
2. Go to the Client Auth view
3. Check the Development tokens setting and save your changes
4. Click the Connect button in the top bar
5. Enter a user ID:
   • If your Sync Streams/Rules data isn’t filtered by user (same data syncs to all users), you can use any value (e.g., test-user).

• If your data is filtered by parameters, use a user ID that matches a user in your database. PowerSync uses this (e.g. auth.user_id() in Sync Streams or request.user_id() in Sync Rules) to determine what to sync.

6. Click Generate Token and copy the token

Development tokens expire after 12 hours.

Self-Hosted

Follow the steps below. Steps 1 and 2 configure signing keys and your PowerSync Service config; in Step 3 you can use the PowerSync CLI (recommended) or the test-client to generate the token.

1. Step 1: Generate signing keys

   Generate a temporary private/public key-pair (RS256) or shared key (HS256) for JWT signing and verification.

   RS256

   Use an online JWK generator like mkjwk.org (select RSA, 2048 bits, Signature use, RS256 algorithm).

   Or generate locally with Node.js:

   # Install pem-jwk if needed
   npm install -g pem-jwk
   
   # Generate private key
   openssl genrsa -out private-key.pem 2048
   
   # Convert public key to JWK format
   openssl rsa -in private-key.pem -pubout | pem-jwk
   

   HS256

   Use an online JWK generator like mkjwk.org (select oct, 256 bits, Signature use, HS256 algorithm) - this outputs base64url directly.

   Or generate and convert using OpenSSL:

   # Generate and convert to base64url
   openssl rand -base64 32 | tr '+/' '-_' | tr -d '='
   

   For production environments, shared secrets (HS256) are not recommended.

2. Step 2: Update your config

   Add the client_auth parameter to your PowerSync config (e.g. service.yaml):

   RS256

   Copy the JWK values from mkjwk.org or the pem-jwk output, then add to your config:

   service.yaml

   # Client (application end user) authentication settings
   client_auth:
     # static collection of public keys for JWT verification
     jwks:
       keys:
         - kty: 'RSA'
           n: '[rsa-modulus]'
           e: '[rsa-exponent]'
           alg: 'RS256'
           kid: 'dev-key-1'
   

   HS256

   Copy the k value from mkjwk.org or the OpenSSL output, then add to your config:

   service.yaml

   # Client (application end user) authentication settings
   client_auth:
     audience: ['http://localhost:8080', 'http://127.0.0.1:8080']
     # static collection of public keys for JWT verification
     jwks:
       keys:
         - kty: oct
           alg: 'HS256'
           k: '[base64url-encoded-shared-secret]'
           kid: 'dev-key-1'
   

   These examples use static jwks: keys: for simplicity. For production, we recommend using jwks_uri to point to a JWKS endpoint instead. See Custom Authentication for more details.

3. Step 3: Generate a development token

   Choose either the PowerSync CLI (recommended) or the test-client:

   CLI (recommended)

   Apply your config changes (e.g. restart your PowerSync Service or run powersync docker reset if running locally with Docker), then run:

   powersync generate token --subject=test-user
   

   Replace test-user with the user ID you want to authenticate:

   • If your Sync Streams/Rules data isn’t filtered by user (same data syncs to all users), you can use any value (e.g., test-user).
   • If your data is filtered by parameters, use a user ID that matches a user in your database. PowerSync uses this (e.g. auth.user_id() in Sync Streams or request.user_id() in Sync Rules) to determine what to sync.

   test-client

   1. If you have not done so already, clone the powersync-service repo
   2. Install and build:

   • In the project root: pnpm install and pnpm build
   • In the test-client directory: pnpm build

   3. Generate a token from the test-client directory, pointing at your config file:

   node dist/bin.js generate-token --config path/to/service.yaml --sub test-user
   

   Replace test-user with the user ID you want to authenticate:

   • If your Sync Streams/Rules data isn’t filtered by user (same data syncs to all users), you can use any value (e.g., test-user).
   • If your data is filtered by parameters, use a user ID that matches a user in your database. PowerSync uses this (e.g. auth.user_id() in Sync Streams or request.user_id() in Sync Rules) to determine what to sync.

Development tokens expire after 12 hours.

Usage

Development tokens can be used for testing purposes either with the Sync Diagnostics Client, the test-client, or your app itself (for development purposes).

Using with Sync Diagnostics Client

The Sync Diagnostics Client allows you to quickly test syncing and inspect a user’s SQLite database, to verify that your PowerSync Service configuration and Sync Streams / Sync Rules behave as expected.

1. Open the Sync Diagnostics Client
2. Enter the generated development token at PowerSync Token.
3. Enter your PowerSync Service endpoint URL at PowerSync Endpoint unless already prepopulated.
4. Click Proceed.
5. Wait for the syncing to complete and inspect the synced data in SQLite.

Using with test-client

The test-client is useful for testing of syncing without persisting anything to a client-side SQLite database. Amongst other things, it can be used for load testing, simulating many client syncing concurrently. Consult the README for details on how to provide the development token as argument to test-client supported commands.

Using with Your Application

To use the temporary development token in your application, update the fetchCredentials() function in your backend connector to return the generated token.

React Native, Web & Capacitor (TS)

async fetchCredentials(): Promise<PowerSyncCredentials> {
  // for development: use development token
  return {
    endpoint: 'https://your-instance.powersync.com',
    token: 'your-development-token-here'
  };
}