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

# 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

<Tabs>
  <Tab title="PowerSync Cloud">
    1. In the [PowerSync Dashboard](https://dashboard.powersync.com/), 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 <Tooltip tip="Values such as user ID that are used to determine which data syncs to which user.">parameters</Tooltip>, 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

    <Note>
      Development tokens expire after 12 hours.
    </Note>
  </Tab>

  <Tab title="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](https://github.com/powersync-ja/powersync-service/tree/main/test-client) to generate the token.

    <Steps>
      <Step title="Step 1: Generate signing keys">
        Generate a temporary private/public key-pair (RS256) or shared key (HS256) for JWT signing and verification.

        <Tabs>
          <Tab title="RS256">
            Use an online JWK generator like [mkjwk.org](https://mkjwk.org/) (select RSA, 2048 bits, Signature use, RS256 algorithm).

            Or generate locally with Node.js:

            ```bash theme={null}
            # 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
            ```
          </Tab>

          <Tab title="HS256">
            Use an online JWK generator like [mkjwk.org](https://mkjwk.org/) (select oct, 256 bits, Signature use, HS256 algorithm) - this outputs base64url directly.

            Or generate and convert using OpenSSL:

            ```bash theme={null}
            # Generate and convert to base64url
            openssl rand -base64 32 | tr '+/' '-_' | tr -d '='
            ```

            <Warning>
              For production environments, shared secrets (HS256) are not recommended.
            </Warning>
          </Tab>
        </Tabs>
      </Step>

      <Step title="Step 2: Update your config">
        Add the `client_auth` parameter to your PowerSync config (e.g. `service.yaml`):

        <Tabs>
          <Tab title="RS256">
            Copy the JWK values from [mkjwk.org](https://mkjwk.org/) or the `pem-jwk` output, then add to your config:

            ```yaml service.yaml theme={null}
            # 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'
            ```
          </Tab>

          <Tab title="HS256">
            Copy the `k` value from mkjwk.org or the OpenSSL output, then add to your config:

            ```yaml service.yaml theme={null}
            # 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'
            ```
          </Tab>
        </Tabs>

        <Note>
          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](/configuration/auth/custom) for more details.
        </Note>
      </Step>

      <Step title="Step 3: Generate a development token">
        Choose either the [PowerSync CLI](/tools/cli) (recommended) or the test-client:

        <Tabs>
          <Tab title="CLI (recommended)">
            Apply your config changes (e.g. restart your PowerSync Service or run `powersync docker reset` if running locally with Docker), then run:

            ```bash theme={null}
            powersync generate token --subject=test-user
            ```

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

            * If your Sync Streams aren'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 <Tooltip tip="Values such as user ID that are used to determine which data syncs to which user.">parameters</Tooltip>, use a user ID that matches a user in your database. PowerSync uses this value (e.g. via `auth.user_id()`) to determine what to sync.
          </Tab>

          <Tab title="test-client">
            1. If you have not done so already, clone the [`powersync-service` repo](https://github.com/powersync-ja/powersync-service/tree/main)
            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:

            ```bash theme={null}
            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 aren'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 <Tooltip tip="Values such as user ID that are used to determine which data syncs to which user.">parameters</Tooltip>, use a user ID that matches a user in your database. PowerSync uses this value (e.g. via `auth.user_id()`) to determine what to sync.
          </Tab>
        </Tabs>
      </Step>
    </Steps>

    <Note>
      Development tokens expire after 12 hours.
    </Note>
  </Tab>
</Tabs>

## Usage

Development tokens can be used for testing purposes either with the [Sync Diagnostics Client](https://diagnostics-app.powersync.com), the [test-client](https://github.com/powersync-ja/powersync-service/tree/main/test-client), or your app itself (for development purposes).

### Using with Sync Diagnostics Client

The [Sync Diagnostics Client](https://diagnostics-app.powersync.com) 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](https://diagnostics-app.powersync.com)
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](https://github.com/powersync-ja/powersync-service/tree/main/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](https://github.com/powersync-ja/powersync-service/tree/main/test-client#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](/configuration/app-backend/client-side-integration) in your *backend connector* to return the generated token.

<CodeGroup>
  ```typescript React Native, Web & Capacitor (TS) theme={null}
  async fetchCredentials(): Promise<PowerSyncCredentials> {
    // for development: use development token
    return {
      endpoint: 'https://your-instance.powersync.com',
      token: 'your-development-token-here'
    };
  }
  ```

  ```typescript Node.js (TS) theme={null}
  async fetchCredentials() {
    // for development: use development token
    return {
        endpoint: 'https://your-instance.powersync.com',
        token: 'your-development-token-here'
    };
  }
  ```

  ```kotlin Kotlin theme={null}
  override suspend fun fetchCredentials(): PowerSyncCredentials {
    // for development: use development token
    return PowerSyncCredentials(
      endpoint = "https://your-instance.powersync.com",
      token = "your-development-token-here"
    )
  }
  ```

  ```swift Swift theme={null}
  func fetchCredentials() async throws -> PowerSyncCredentials {
    // for development: use development token
    return PowerSyncCredentials(
      endpoint: "https://your-instance.powersync.com",
      token: "your-development-token-here"
    )
  }
  ```

  ```dart Dart/Flutter theme={null}
  @override
  Future<PowerSyncCredentials> fetchCredentials() async {
    return PowerSyncCredentials(
      endpoint: 'https://your-instance.powersync.com',
      token: 'your-development-token-here'
    );
  }
  ```

  ```csharp .NET theme={null}
  public async Task<PowerSyncCredentials?> FetchCredentials()
  {
      var powerSyncUrl = "https://your-instance.powersync.com";
      var authToken = "your-development-token-here";

      // Return credentials with PowerSync endpoint and JWT token
      return new PowerSyncCredentials(powerSyncUrl, authToken);
  }
  ```

  ```rust Tauri (Rust) theme={null}
  // For Tauri, fetchCredentials is implemented inside your Rust BackendConnector
  async fn fetch_credentials(&self) -> Result<PowerSyncCredentials, PowerSyncError> {
      Ok(PowerSyncCredentials {
          endpoint: "https://your-instance.powersync.com".to_string(),
          token: "your-development-token-here".to_string(),
      })
  }
  ```
</CodeGroup>