Managing Secrets

Secrets let you store sensitive configuration values in Serverpod Cloud without exposing them in your application code. Secrets are values like API keys, passwords, and tokens that your application needs to function but shouldn't be hardcoded in your source code. In Serverpod Cloud, secrets are:

Encrypted at rest
Never logged or displayed after creation
Automatically injected as environment variables into your application
For non-sensitive configuration values, use environment variables

Creating Secrets

Use the scloud secret create command to add a new secret:

scloud secret create --name API_KEY --value "my_secret_value"

Confirm the secret was created successfully:
```
Secret API_KEY created successfully.
```

Listing Secrets

To view all secrets (names only, not values):

scloud secret list

Example output:

Secret name
-----------
API_KEY

Deleting Secrets

Use the scloud secret delete command to remove a secret:
```
scloud secret delete --name API_KEY
```

Confirm the deletion when prompted:

Are you sure you want to delete the secret API_KEY? [y/N]: y

Accessing Secrets in Your Code

Secrets are automatically injected as environment variables into your Serverpod application. You can access them using Dart's Platform.environment API:

import 'dart:io';

class PaymentEndpoint extends Endpoint {
  Future<bool> processPayment(Session session, double amount) async {
    // Access the secret as an environment variable
    final apiKey = Platform.environment['API_KEY'];
    
    if (apiKey == null) {
      throw Exception('API_KEY environment variable not set');
    }
    
    // Use the API key to process payment
    // ...
    
    return true;
  }
}

Automatically Managed Secrets

Serverpod Cloud automatically manages certain secrets and injects them as environment variables into your application's runtime environment. You don't need to manually create or manage these secrets.

Currently, the following secrets are automatically managed:

Secret Name	Description
SERVERPOD_DATABASE_PASSWORD	Automatically populated when the database feature is enabled. This contains the password for connecting to your Serverpod managed database.

💡 Best Practices

Use descriptive names for secrets (e.g., PAYMENT_API_KEY instead of just API_KEY)
Don't store secrets in version control, even in private repositories
Add validation to ensure required secrets are present before using them
Use different secrets for different environments (development, staging, production)
Document required secrets in your project README

🧪 Example: Complete Secret Management

Here's a more complete example of using secrets in a Serverpod Cloud application:

// secret_config.dart
import 'dart:io';

// Extension to make the secrets accessible from the session
extension AccessibleSecrets on Session {
  SecretConfig get secrets => SecretConfig.instance;
}

// Configuration class to centralize secret access
class SecretConfig {
  final String paymentApiKey;

  SecretConfig._({
    required this.paymentApiKey,
  });

  static void init() {
    _instance = SecretConfig._fromEnvironment();
  }

  static SecretConfig? _instance;
  static SecretConfig get instance {
    return _instance ??= SecretConfig._fromEnvironment();
  }

  factory SecretConfig._fromEnvironment() {
    // Required secrets with validation
    final apiKey = Platform.environment['PAYMENT_API_KEY'];
    
    if (apiKey == null) {
      throw Exception('PAYMENT_API_KEY environment variable not set');
    }
    
    return SecretConfig._(
      paymentApiKey: apiKey,
    );
  }
}

Initialize the secrets when starting Serverpod:

// server.dart
import 'package:serverpod/serverpod.dart';

import 'src/generated/protocol.dart';
import 'src/generated/endpoints.dart';

void run(List<String> args) async {
  final pod = Serverpod(
    args,
    Protocol(),
    Endpoints(),
  );

  SecretConfig.init();

  // other setup code ...

  await pod.start();
}

Inside an endpoint you can access the secrets through the session object. This allows you to use secrets throughout your application in a clean, centralized way:

class PaymentEndpoint extends Endpoint {
  Future<String> createPayment(Session session, double amount) async {
    // Access secrets through the session extension
    final apiKey = session.secrets.paymentApiKey;
    
    // Use the secrets to process payment
    return PaymentService.create(apiKey);
  }
}

Creating Secrets​

Listing Secrets​

Deleting Secrets​

Accessing Secrets in Your Code​

Automatically Managed Secrets​

💡 Best Practices​

🧪 Example: Complete Secret Management​