Secrets

With secrets, Squid provides state of the art support for managing sensitive data like API keys, passwords, certificates and more. While most secret management can be done in the Squid Cloud Console, the Squid Client SDK also provides a secrets API that allows for programmatic management.

const { value } = await squid.secrets.get('DATABASE_PASSWORD');

Programmatic secret management is useful for automatically rotating API keys, periodically refreshing passwords, dynamically creating services, and more. The Squid Client SDK provides a way to manage both your custom secrets and your application's API keys.

Caution

To manage secrets from the Squid Client SDK, your client must be initialized with your application's API key. This can be done using the apiKey option, and should never be done from a user facing application. Secret management should only be performed in secure environment, such as in your Squid Backend.

Benefits

Squid Cloud offers a robust secrets management platform that dynamically handles all aspects required in building a secure application, whether API keys, passwords, access tokens, or applying policies and lifecycles around them. Secrets management can efficiently, securely, and easily done in the Squid Cloud Console or through the Client SDK. Secrets minimize the risk of data breaches and unauthorized access.

Additionally, this setup enables the secure injection of sensitive information, like authentication secrets, into API requests. These secrets are kept hidden from the clients making the requests, ensuring the API's integrity and bolstering security.

Use cases

• Securely injecting API keys or other authentication secrets into API requests
• Enabling API calls directly and securely from the client
• Implementing API key verification
• Implementing API key rotation with a Scheduler in Squid
• Implementing a webhook for API key validation

Custom secrets

Secrets can be managed using standard CRUD operations provided by the client. The API can be used as follows:

Getting a secret

To access a secret by name, you can call the get method. The method will return a secret entry, which includes the value and the time that the secret was lastUpdated (in milliseconds), or undefined if the secret does not exist.

const result = await squid.secrets.get('SECRET_NAME');
// {
//   key: 'SECRET_NAME',
//   value: 'your_value',
//   lastUpdated: 1692306991724
// }

Getting all secrets

To get a map of all secrets, you can call the getAll method. Each entry in the map will include a value and the time that the secret was lastUpdated (in milliseconds).

const result = await squid.secrets.getAll();
// {
//   'SECRET_NAME': {
//     key: 'SECRET_NAME',
//     value: 'your_value',
//     lastUpdated: 1692306991724
//   }
// }

Creating or updating a secret

To create new secrets, or update an existing ones, you can use the upsert function, passing the key and value of your secret as parameters. The secret will be created or updated. The call will return the created or updated secret.

const result = await squid.secrets.upsert('SECRET_NAME', 'your_new_value');
// {
//   key: 'SECRET_NAME',
//   value: 'your_new_value',
//   lastUpdated: 1692306991724
// }

To update multiple secrets at once, use the upsertMany method. The function takes an array of secrets to update where each secret is an object with key and value attributes.

const result = await squid.secrets.upsertMany([
  { key: 'SECRET_NAME', value: 'your_new_value' },
  { key: 'OTHER_SECRET_NAME', value: 'your_other_value' },
]);
// [{
//   key: 'SECRET_NAME',
//   value: 'your_new_value',
//   lastUpdated: 1692306991724
// },
// {
//   key: 'OTHER_SECRET_NAME',
//   value: 'your_other_value',
//   lastUpdated: 1692306991724
// }]

Deleting a secret

To delete a secret, call the delete method with the name of the secret you want to delete.

await squid.secrets.delete('SECRET_NAME');

To delete multiple secrets at once, use the deleteMany method. The function takes an array of strings containing the names of the secrets to delete.

const result = await squid.secrets.deleteMany([
  'SECRET_NAME',
  'OTHER_SECRET_NAME',
]);

API keys

Squid API keys can also be managed with the squid.secrets attribute. However as Squid handles the generation of the API keys, a value cannot be passed when creating or updating an API key.

Getting an API key

To access an API key by name, call the apiKeys.get method. If the API key does not exist, then the method returns a promise that resolves to unefined. If the key exists, then the method returns a promise that resolves to a secret entry object consisting of a key, a value and the time that the secret was lastUpdated, in milliseconds.

const result = await squid.secrets.apiKeys.get('API_KEY_NAME');
// {
//   key: 'API_KEY_NAME',
//   value: 'a123b456-cd78-9e90-f123-gh45i678j901',
//   lastUpdated: 1692306991724
// }

Getting all API keys

To get a map of all API keys, you can call the apiKeys.getAll method. Each entry in the map will include a value and the time that the key was lastUpdated (in milliseconds).

const result = await squid.secrets.apiKeys.getAll();
// {
//   'API_KEY_NAME': {
//     key: 'API_KEY_NAME',
//     value: 'a123b456-cd78-9e90-f123-gh45i678j901e',
//     lastUpdated: 1692306991724
//   }
// }

Creating or updating an API key

To create a new API key or rotate an existing one, use the apiKeys.upsert method. Pass the name of your key as a parameter. Squid generates the new key for you, and returns the value of the key in the response.

const result = await squid.secrets.apiKeys.upsert('API_KEY_NAME');
// {
//   key: 'API_KEY_NAME',
//   value: 'a123b456-cd78-9e90-f123-gh45i678j901e',
//   lastUpdated: 1692306991724
// }

Deleting an API key

To delete an API key, call the delete method, passing the name of the key.

await squid.secrets.delete('API_KEY_NAME');

Secrets in the Squid backend

In the Squid backend, you can access an object containing your secrets directly using this.secrets. For example, you can access the secret value of a secret called 'SECRET_NAME':

Backend code

this.secrets['SECRET_NAME']; // 'your_value'

Use Cases

Secret and API key management can be powerful when combined with Squid's backend functions like schedulers and triggers. The following example shows a use case for programmatic secret management.

Rotating an API Key on a schedule

@scheduler("rotate-api-key", CronExpression.EVERY_DAY_AT_MIDNIGHT)
rotateApiKey() {
  const { lastUpdated } = await this.squid.secrets.apiKeys.get('MY_API_KEY');
  // If the key is over 30 days old
  if (lastUpdated < Date.now() - (30 * 86400000)) {
    await this.squid.secrets.apiKeys.upsert('MY_API_KEY')
  }
}

To learn more about schedulers, check out the documentation on schedulers.