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

# Usages

> Guide to using the Locker Secrets Manager SDK for Python

## Configure Access Keys

The SDK needs to be configured with your access key id and your secret access key, which is available in your Locker Secrets Dashboard. These keys must not be disclosed. If you reveal these keys, you need to revoke them immediately. Environment variables are a good solution and they are easy to consume in most programming languages.

### Linux/MacOS

```bash theme={null}
export ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
export SECRET_ACCESS_KEY=<YOUR_SECRET_ACCESS_KEY>
```

### Windows

**PowerShell**

```powershell theme={null}
$Env:ACCESS_KEY_ID = '<YOUR_ACCESS_KEY_ID>'
$Env:SECRET_ACCESS_KEY = '<SECRET_ACCESS_KEY>'
```

**Command Prompt**

```bash theme={null}
set ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
set SECRET_ACCESS_KEY=<YOUR_SECRET_ACCESS_KEY>
```

You also need to set the `api_base` value (default is `https://api.locker.io/locker_secrets`).

If you need to set custom headers, also set the `headers` value in the `options` parameter. You can now use the SDK to get or set values:

```python theme={null}
from locker import Locker

api_base = "your_base_api.host"
locker = Locker(
    api_base=api_base,
    options={"headers": headers}
)
```

You can also pass parameters in the `Locker()` method or use the shared credential file (`~/.locker/credentials`), but we do not recommend these ways.

```python theme={null}
locker = Locker(
    access_key_id=os.get_env("<YOUR_ACCESS_KEY_ID>"),
    secret_access_key=os.get_env("<YOUR_SECRET_ACCESS_KEY>"),
    api_base=api_base,
    options={"headers": headers}
)
```

***

## List Secrets

Use `.list()` to get all the secrets in your project.

```python theme={null}
secrets = locker.list()
for secret in secrets:
    print(secret.id, secret.key, secret.value)
```

***

## Get Secret Values

This function will get the secret value by a key. If the key does not exist, SDK will return the default\_value

```python theme={null}
secret_value = locker.get("REDIS_CONNECTION", default_value="TheDefaultValue")
print(secret_value)
```

You could get a secret value by a secret key and specific environment name by the `environment_name` parameter.
If the key does not exist, SDK will return the default\_value

```python theme={null}
secret_value = locker.get_secret(
    "REDIS_CONNECTION",
    environment_name="staging",
    default_value="TheDefaultValue"
)
print(secret_value)
```

***

## Create Secrets

Use the `.create()` function to create a new secret:

```python theme={null}
secret = locker.create(key="YOUR_NEW_SECRET_KEY", value="YOUR_NEW_SECRET_VALUE")
```

Create a new secret with a specific environment:

```python theme={null}
secret = locker.create(key="YOUR_NEW_SECRET_KEY", value="YOUR_NEW_SECRET_VALUE", environment_name="staging")
```

***

## Update Secrets

Use `.modify()` function to update the value of the secret

```python theme={null}
secret = locker.modify(key="YOUR_NEW_SECRET_KEY", value="UPDATED_SECRET_VALUE")
print(secret.key, secret.value, secret.environment_name)
```

Update a secret value by the secret key and the specific environment name

```python theme={null}
secret = locker.modify(key="YOUR_NEW_SECRET_KEY", value="UPDATED_SECRET_VALUE", environment_name="staging")
print(secret.key, secret.value, secret.environment_name)
```

***

## List Environments

Use `.list_environments()` to get all environments in your project

```python theme={null}
environments = locker.list_environments()
for env in environments:
    print(env.name, env.external_url)
```

***

## Retrieve an Environment

To retrieve an environment by name, use `.get_environment()`

```python theme={null}
prod_env = locker.get_environment("prod")
print(prod_env.name, prod_env.external_url)
```

***

## Create an Environment

To create a new environment, use `.create_environment()`

```python theme={null}
new_environment = locker.create_environment(name="staging", external_url="staging.host")
print(new_environment.name, new_environment.external_url)
```

***

## Update an Environment

To update the `external_url` of the environment by name, use `.update_environment()`

```python theme={null}
environment = locker.modify_environment(name="staging", external_url="new.staging.host")
```

***

## Error Handling

Locker Secret SDK offers some kinds of errors. They can reflect external events, like invalid credentials, network interruptions, or code problems, like invalid API calls.

If an immediate problem prevents a function from continuing, the SDK raises an exception. It’s a best practice to catch and handle exceptions. To catch an exception, use Python’s `try/except` syntax. Catch `locker.error.LockerError` or its subclasses to handle Locker-specific exceptions only. Each subclass represents a different kind of exception. When you catch an exception, you can use its class to choose a response.

Example:

```python theme={null}
from locker import Locker
from locker.error import LockerError

# Create a new secret and handle error
try:
    new_secret = locker.create(key="YOUR_KEY", value="your_key_value", environment_name="staging")
    print(new_secret.key, new_secret.value, new_secret.description, new_secret.environment_name)
except LockerError as e:
    print(e.user_message)
    print(e.http_body)
```

In the SDK, error objects belong to `locker.error.LockerError` and its subclasses. Use the documentation for each class for advice about how to respond.

| **Code**            | **HTTP Status** | **Name**                | **Class**                            | **Description**                                                                          |
| ------------------- | --------------- | ----------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------- |
| `unauthorized`      | 401             | Authentication Error    | `locker.error.AuthenticationError`   | Invalid `access_client_id` or invalid `secret_access_key`                                |
| `permission_denied` | 403             | Permission Denied Error | `locker.error.PermissionDeniedError` | Your credential does not have enough permission to execute this operation                |
| `rate_limit`        | 429             | Rate Limit Error        | `locker.error.RateLimitError`        | Too many requests                                                                        |
| `not_found`         | 404             | Resource Not Found      | `locker.error.ResourceNotFoundError` | The requested resource is not found                                                      |
| `server_error`      | 500             | API Server Error        | `locker.error.APIServerError`        | Something went wrong on Locker's end (These are rare)                                    |
| `http_error`        | 503             | API Connect Error       | `locker.error.APIConnectionError`    | The request to API server error. Check your network connection                           |
| `cli_error`         | —               | CLI Run Error           | `locker.error.CliRunError`           | The encryption/decryption binary runs error by invalid local data, process interruptions |
| `locker_error`      | —               | General Locker Error    | `locker.error.LockerError`           | The general error                                                                        |

***

## Logging

The library can be configured to emit logging that will give you better insight into what it's doing. There are some levels: `debug`, `info`, `warning`, `error`.

The `info` logging level is usually most appropriate for production use, but `debug` is also available for more verbosity.

There are a few options for enabling it:

**1. Set the environment variable `LOCKER_LOG` to the value `debug`, `info`, `warning` or `error`**

```bash theme={null}
$ export LOCKER_LOG=debug
```

**2. Set `log` when initializing the Locker object:**

```python theme={null}
from locker import Locker

locker = Locker(log="debug")
```

**3. Enable it through Python's logging module:**

```python theme={null}
import logging
logging.basicConfig()
logging.getLogger('locker').setLevel(logging.DEBUG)
```