Secrets

With secrets, Squid provides support for managing sensitive data like API keys, passwords, certificates and more. Secret management can be done both via the Squid Console and the Squid Client SDK.

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 a secure environment, such as in your Squid Backend.

Secrets minimize the risk of data breaches and unauthorized access. Squid secrets can be useful for many situations where security is important, including:

• 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

Custom secrets

Secrets can be managed using standard CRUD (create, read, update, delete) 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.apiKey.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'

Example: Rotating an API Key on a schedule

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.

@scheduler("rotate-api-key", CronExpression.EVERY_DAY_AT_MIDNIGHT)
async 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.