Usages

Configure Access Keys

The SDK needs to be configured with your access key which is available in your Locker Secrets Dashboard. Initialize the accessKeyId and secretAccessKey to their value. You also need to set apiBase value (default value is https://secrets-core.locker.io).

import { Locker } from 'lockerpm'
// You should not hardcode access key credentials. Instead, load them from environment variables
const locker = new Locker({
  accessKeyId: process.env.LOCKER_ACCESS_KEY_ID,
  secretAccessKey: process.env.LOCKER_ACCESS_KEY_SECRET,
  apiBase: '<your base api url>'
})

All initialization options are listed below:

Key	Description	Type	Required
`accessKeyId`	Your access key id	`string`	✅
`accessKeySecret`	Your access key secret	`string`	✅
`apiBase`	Your server base API URL, default value is https://api.locker.io/locker_secrets	`string`	❌
`headers`	Custom headers for API calls	`{[header: string]: string}`	❌
`unsafe`	Set TLS to unsafe if you use a server with self-signed certificate, default value is `false`	`boolean`	❌
`logLevel`	Refer to Logging, default value is `1`	`number`	❌

You can now use the SDK to get or set values.

Get secrets

Methods:

list: list all secrets

list: () => Promise<Secret[]>

listSync: get all secrets, but synchronized

listSync: () => Secret[]

get: get a secret by key and environment name (optional, defaults to ALL environment), can return a default value if no secret is found

get: (key: string, env?: string, defaultValue?: string) => Promise<string | undefined>

getSync: get a secret but synchronized

getSync: (key: string, env?: string, defaultValue?: string) => string | undefined

Example:

// Get list secrets quickly
const secrets = await locker.list()
// or
const secrets = locker.listSync()

// Get a secret value by secret key
// Replace 'ENVIRONMENT' with null or undefined for the enviroment ALL
const secretValue1 = await locker.get('SECRET_NAME_1')
const secretValue2 = await locker.get('SECRET_NAME_2', 'ENVIRONMENT')
const secretValue3 = await locker.get('SECRET_NAME_3', 'ENVIRONMENT', 'default value')
// or
const secretValue3 = locker.getSync('SECRET_NAME_3', 'ENVIRONMENT', 'default value')

Get a secret value

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

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

secret_value = locker.get_secret(
	"REDIS_CONNECTION", 
	environment_name="staging", 
	default_value="TheDefaultValue"
)
print(secret_value)

Create secrets

Methods:

create: create a new secret with a name, value, environment name (optional) and description (optional). You cannot create secrets with the same key in the same environment. Returns the new secret.

create: (data: { key: string; value: string; environmentName?: string; description?: string }) => Promise<Secret>

Example

// Create new secret
const secret1 = await locker.create({
  key: 'key',
  value: 'value',
	description: 'a new secret'
})

// This will throw an Error
const secret2 = await locker.create({
  key: 'key',
  value: 'value 2',
})

// Use another env, this will not throw an Error
const secret3 = await locker.create({
  key: 'key',
  value: 'value',
	environmentName: 'prod'
})

// This will throw an Error
const secret4 = await locker.create({
  key: 'key',
  value: 'value 2',
	environmentName: 'prod'
})

Update secrets

Methods:

modify: edit the value, environment name or description of a secret. You cannot change the secret’s key. You also cannot change the environment to a new environment that already has a secret with the same name. Returns the updated secret.

modify: (key: string, env: string, data: { value: string; environmentName?: string; description?: string }) => Promise<Secret>

Example:

// Update the secret "key" of env "ALL"
const secret = await locker.modify('key', '', {
  value: 'value 2',
	description: 'desc'
})

// Update the secret "key" of env "prod"
const secret = await locker.modify('key', 'prod', {
  value: 'value 2',
	environmentName: 'prod'
})

// This will update the env from "prod" to "ALL"
const secret = await locker.modify('key', 'prod', {
  value: 'value 2'
})

// This will update the env from "ALL" to "prod"
const secret = await locker.modify('key', '', {
  value: 'value 2',
	environmentName: 'prod'
})

Get environments

Methods:

listEnvironments: List all environments

listEnvironments: () => Promise<Environment[]>

listEnvironmentsSync: List all environments but synchronized

listEnvironmentsSync: () => Environment[]

getEnvironment: get an environment by name

getEnvironment: (name: string) => Promise<Environment | undefined>

getEnvironmentSync: get an environment but synchronized

getEnvironmentSync: () => Environment | undefined

Example:

// List environments
const environments = await locker.listEnvironments()
// or
const environments = locker.listEnvironmentsSync()

// Get an environment object by name
const environment = await locker.getEnvironment('prod')
// or
const environment = locker.getEnvironmentSync('prod')

Retrieve an environment

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

prod_env = locker.get_environment("prod")
print(prod_env.name, prod_env.external_url)

Create an environment

Methods:

createEnvironment: create a new environment with a name, external url and description (optional). You cannot create environments with the same name. Returns the new environment.

createEnvironment: (data: { name: string; externalUrl: string; description?: string }) => Promise<Environment>

Example:

// Create a new environment
const env1 = await locker.createEnvironment({
  name: 'prod',
  externalUrl: 'product.prod',
	description: 'testing'
})

// This will throw an error
const env2 = await locker.createEnvironment({
  name: 'prod',
  externalUrl: 'product.prod.example'
})

Update an environment

Methods:

modifyEnvironment: edit the description and external url of an environment. You cannot change the name of an environment. Returns the updated environment.

modifyEnvironment: (name: string, data: { externalUrl: string; description?: string }) => Promise<Environment>

Example:

// Update an environment by name
const env = await locker.modifyEnvironment("name", {
  externalUrl: 'new value',
})

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:

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)
    print(e.code)
    print(e.status_code)

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 `secret_access_key`
`permission_denied`	403	Permission Denied Error	`locker.error.PermissionDeniedError`	Your credential does not have enough permission
`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`	Network error
`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: NONE (0), ERROR (1), DEBUG (2). Set the logging level when creating a Locker instance to enabling it:

const locker = new Locker({
  // ...
  logLevel: 1  // default is ERROR
})

Getting Started

Project Creation for Storing Secrets

Storing and Managing Secrets

CLI and SDK Installation

Integration

Plans and Pricing

Self-hosted Deployment

Release Notes

Configure Access Keys

Get secrets

Get a secret value

Create secrets

Update secrets

Get environments

Retrieve an environment

Create an environment

Update an environment

Error Handling

Logging

​Configure Access Keys

​Get secrets

​Get a secret value

​Create secrets

​Update secrets

​Get environments

​Retrieve an environment

​Create an environment

​Update an environment

​Error Handling

​Logging

Configure Access Keys

Get secrets

Get a secret value

Create secrets

Update secrets

Get environments

Retrieve an environment

Create an environment

Update an environment

Error Handling

Logging