Managing Passwords

The scloud password command provides management of passwords for Serverpod Cloud projects. Passwords are automatically prefixed with SERVERPOD_PASSWORD_ and will be injected as environment variables. Passwords defined by this command can be accessed with Serverpod's getPassword() function.

note

If you need to set a secret without the SERVERPOD_PASSWORD_ prefix, you can do so by using the secret create command.

Understanding Password Categories

Passwords are grouped by category:

• Custom: User-defined passwords that are not part of the platform
• Services: Passwords for services like databases, insights, etc.
• Auth: Passwords for authentication like JWT, email, for package serverpod_auth_idp_server
• Legacy Auth: Passwords for the legacy authentication module

Listing Passwords

To view all passwords (both user-set and platform-managed):

scloud password list

note

Password values are never displayed for security reasons. Only the password names are shown, grouped by category.

Setting Passwords

Use the scloud password set command to set a password:

scloud password set insight "my_insight_password"

You can also set a password from a file:

scloud password set insight --from-file password.txt

The password name should be provided without the SERVERPOD_PASSWORD_ prefix. The prefix is automatically added by Serverpod Cloud.

note

Setting a platform-managed password will override the existing password. The original password will not be lost and can be activated again by unsetting the password.

Unsetting Passwords

To remove a user-set password:

scloud password unset insight

warning

You can only unset user-set passwords. Platform-managed passwords cannot be unset, but they can be overridden by setting a custom value.

If you unset a password that was overriding a platform-managed password, the original platform-managed password will be restored.

Accessing Passwords in Your Code

Passwords are accessible in your Serverpod application using the getPassword() function from the session:

import 'package:serverpod/serverpod.dart';

class MyEndpoint extends Endpoint {
  Future<void> myMethod(Session session) async {
    // Access password using getPassword()
    // This accesses SERVERPOD_PASSWORD_mySecretPassword
    final password = await session.serverpod.getPassword('mySecretPassword');

    if (password == null) {
      throw Exception('Password not configured');
    }
    
    // Use the password to connect to the database
    // ...
  }
}

The getPassword() function automatically looks for the password with the SERVERPOD_PASSWORD_ prefix. For example, calling getPassword('insights') will access SERVERPOD_PASSWORD_insights.

Common Use Cases

Insights Passwords

Set a custom insights password:

scloud password set insights "my_secure_password"

Will be used by the insights service to authenticate requests.

API Key Passwords

Set an API key password:

scloud password set apiKey "my_api_key"

Access in code:

final apiKey = await session.serverpod.getPassword('apiKey');

Platform-Managed vs User-Set Passwords

Platform-Managed Passwords

Serverpod Cloud automatically manages certain passwords for platform services:

• Database passwords (when database feature is enabled)
• Service authentication passwords
• Platform authentication passwords

These passwords are automatically generated and managed by the platform. You can override them by setting a custom value, but you cannot delete them. If you are using the Serverpod Cloud database we recommend to not override the password or your service may no longer be able to connect to the database.

Differences from Secrets

While both passwords and secrets are encrypted and secure, they serve different purposes:

Feature	Passwords	Secrets
Prefix	SERVERPOD_PASSWORD_	None (custom name)
Access method	getPassword() function	Platform.environment
Use case	Serverpod-specific passwords	General sensitive data
Can be updated	✅ Yes	❌ No (delete & recreate)
Platform-managed	✅ Some are	❌ No

Related Documentation

• Configuration Management Overview - Learn when to use secrets vs variables vs passwords
• Managing Secrets - Guide for general sensitive configuration values
• Managing Variables - Guide for non-sensitive configuration values
• CLI Reference: password command - Complete command reference