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

# Username & Password

> Create a username and password secret to store authentication credentials for databases, APIs, SMTP servers, or other services.

Username & Password secrets store authentication credentials as a username/password pair. Use them for database connections, API authentication, SMTP servers, or any service requiring basic credentials.

## Use Cases

* **Database Authentication**: Store credentials for PostgreSQL, MySQL, MongoDB, etc.
* **API Authentication**: Basic auth credentials for REST APIs
* **SMTP/Email Services**: Credentials for email sending services
* **Legacy Systems**: Connect to systems using username/password authentication
* **FTP/SFTP Access**: Credentials for file transfer services

## Configuration Options

| Field      | Description                                 | Required              |
| :--------- | :------------------------------------------ | :-------------------- |
| `username` | The username or account identifier          | Yes                   |
| `password` | The password or secret credential           | Yes                   |
| `encoding` | How values are encoded: `plain` or `base64` | No (default: `plain`) |

<Note>
  Use `encoding: base64` when your credentials contain special characters that might cause parsing issues, or when you're storing pre-encoded credentials from another system.
</Note>

***

## Create a Username & Password Secret

<Tabs>
  <Tab title="Console UI">
    <Steps>
      <Step title="Navigate to Secrets">
        In the Console, navigate to **Secrets** and click **New**, or use the **Create** dropdown in the top-right corner and select **Secret**.
      </Step>

      <Step title="Enter basic information">
        Enter a **Name** and optional **Description**.
      </Step>

      <Step title="Select secret type">
        Select **Username/Password** as the secret type.
      </Step>

      <Step title="Configure credentials">
        Click **Data** in the left pane. Enter the **Username** and **Password**. If your credentials are base64 encoded, enable **Base64 Decode at Runtime** to decode them when accessed.
      </Step>

      <Step title="Create the secret">
        Click **Create**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    cpln secret create-userpass \
      --name db-credentials \
      --username app_user \
      --password 'secure-password-here' \
      --org my-org
    ```

    <Tip>
      Wrap passwords in single quotes to prevent shell interpretation of special characters.
    </Tip>
  </Tab>

  <Tab title="Terraform">
    ```hcl theme={null}
    resource "cpln_secret" "db_credentials" {
      name        = "db-credentials"
      description = "PostgreSQL database credentials"

      userpass {
        username = "app_user"
        password = "secure-password-here"
        encoding = "plain"
      }
    }
    ```

    <Warning>
      This example uses hardcoded credentials for testing. In production, use Terraform variables, environment variables, or integrate with a secrets manager like HashiCorp Vault.
    </Warning>
  </Tab>

  <Tab title="Pulumi">
    <Tabs>
      <Tab title="TypeScript">
        ```typescript theme={null}
        import * as cpln from "@pulumiverse/cpln";

        const dbCredentials = new cpln.Secret("db-credentials", {
          name: "db-credentials",
          description: "PostgreSQL database credentials",
          userpass: {
            username: "app_user",
            password: "secure-password-here",
            encoding: "plain",
          },
        });
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        import pulumiverse_cpln as cpln

        db_credentials = cpln.Secret("db-credentials",
            name="db-credentials",
            description="PostgreSQL database credentials",
            userpass={
                "username": "app_user",
                "password": "secure-password-here",
                "encoding": "plain",
            })
        ```
      </Tab>

      <Tab title="Go">
        ```go theme={null}
        package main

        import (
            "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
            "github.com/pulumiverse/pulumi-cpln/sdk/go/cpln"
        )

        func main() {
            pulumi.Run(func(ctx *pulumi.Context) error {
                _, err := cpln.NewSecret(ctx, "db-credentials", &cpln.SecretArgs{
                    Name:        pulumi.String("db-credentials"),
                    Description: pulumi.String("PostgreSQL database credentials"),
                    Userpass: &cpln.SecretUserpassArgs{
                        Username: pulumi.String("app_user"),
                        Password: pulumi.String("secure-password-here"),
                        Encoding: pulumi.String("plain"),
                    },
                })
                return err
            })
        }
        ```
      </Tab>

      <Tab title="C#">
        ```csharp theme={null}
        using Pulumi;
        using Pulumiverse.Cpln;
        using Pulumiverse.Cpln.Inputs;

        return await Deployment.RunAsync(() =>
        {
            var dbCredentials = new Secret("db-credentials", new SecretArgs
            {
                Name = "db-credentials",
                Description = "PostgreSQL database credentials",
                Userpass = new SecretUserpassArgs
                {
                    Username = "app_user",
                    Password = "secure-password-here",
                    Encoding = "plain",
                },
            });
        });
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

***

## Injecting into Workloads

### As Environment Variables

Reference the username and password separately:

```yaml theme={null}
env:
  - name: DB_USER
    value: "cpln://secret/db-credentials.username"
  - name: DB_PASSWORD
    value: "cpln://secret/db-credentials.password"
```

### As Volume Files

When mounted as a volume, the secret creates two files:

```yaml theme={null}
volumes:
  - uri: "cpln://secret/db-credentials"
    path: /etc/credentials
```

This creates:

* `/etc/credentials/username` containing the username
* `/etc/credentials/password` containing the password

***

## Common Patterns

### PostgreSQL Connection

```yaml theme={null}
kind: secret
name: postgres-credentials
type: userpass
data:
  username: postgres
  password: your-secure-password
```

Workload environment:

```yaml theme={null}
env:
  - name: PGUSER
    value: "cpln://secret/postgres-credentials.username"
  - name: PGPASSWORD
    value: "cpln://secret/postgres-credentials.password"
```

### MongoDB Connection

```yaml theme={null}
kind: secret
name: mongodb-credentials
type: userpass
data:
  username: mongouser
  password: your-secure-password
```

### SMTP Credentials

```yaml theme={null}
kind: secret
name: smtp-credentials
type: userpass
data:
  username: apikey
  password: SG.xxxxx  # SendGrid API key
```

### Basic Auth for APIs

```yaml theme={null}
kind: secret
name: api-credentials
type: userpass
data:
  username: api_client_id
  password: api_client_secret
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use strong, unique passwords">
    Generate random passwords with sufficient length and complexity. Avoid reusing passwords across different services.
  </Accordion>

  <Accordion title="Rotate credentials regularly">
    Establish a rotation schedule for credentials. Update both the secret in Control Plane and the corresponding service.
  </Accordion>

  <Accordion title="Prefer dedicated accounts">
    Create dedicated service accounts rather than using personal credentials. This enables better auditing and easier credential rotation.
  </Accordion>

  <Accordion title="Consider alternative auth methods">
    Where possible, prefer more secure authentication methods like IAM roles, service accounts, or certificate-based auth over username/password.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Opaque Secrets" icon="file-lines" href="/guides/create-secret/opaque">
    Store API keys and other single-value secrets
  </Card>

  <Card title="Using Secrets in Workloads" icon="cube" href="/guides/create-secret/overview#using-secrets-in-workloads">
    Learn how to grant access and inject secrets
  </Card>
</CardGroup>