SDK: API Reference

Complete API reference for the Grizzly SDK.

KeyClient

The main entry point for interacting with the Grizzly platform.

Static Methods

KeyClient.create(options: KeyClientOptions): Promise<IKeyClient>

Creates and initializes a new KeyClient instance.

Parameters:

Parameter	Type	Required	Description
options.host	string	Yes	Base URL of your Grizzly instance (e.g., https://tenant.grizzlycbg.io)
options.asymHost	string	No	URL for Asymmetric Key Service (defaults to {host}/asym)
options.apikey	string	Yes	API Key for authentication
options.keycache.max	number	No	Maximum number of keys to cache in memory

Returns: Promise<IKeyClient>

Example:

const client = await KeyClient.create({
   host: 'https://your-tenant.grizzlycbg.io',
   apikey: 'apikey-123456-1234567890',
   keycache: { max: 100 }
})

---

Properties

ring: IKeyRingWarden (readonly)

Access to the KeyRingWarden for managing KeyRings.

store: IKeyStore (readonly)

The underlying key storage implementation.

utils: KeyClientUtils (readonly)

Utility functions for working with the SDK.

---

Methods

encrypt(data: string | Buffer | Readable, keyring: string, options?: EncryptOptions): Promise<string | Buffer | Readable>

Encrypts data using a specified KeyRing.

Parameters:

Parameter	Type	Required	Description
data	string | Buffer | Readable	Yes	Data to encrypt
keyring	string	Yes	Name of the KeyRing to use
options	EncryptOptions	No	Encryption options
options.asset	string | object	No	Asset metadata (cryptographically signed and embedded in header)
options.outFormat	EncodingFormat	No	Output format: 'string', 'buffer', or 'readable-stream'
options.inEncoding	Encoding	No	Input data encoding
options.outEncoding	Encoding	No	Output data encoding

Returns: Promise<string | Buffer | Readable> - Encrypted data in the same format as input (unless outFormat is specified)

Example:

// Encrypt string
const encrypted = await client.encrypt('Secret data', 'Finance')

// Encrypt with Asset (simple string)
const encrypted = await client.encrypt('User data', 'UserData', {
   asset: 'user-123'
})

// Encrypt with Asset (complex metadata)
const encrypted = await client.encrypt('Sensitive document', 'Documents', {
   asset: {
      id: 'doc-789',
      type: 'contract',
      owner: 'user-456',
      classification: 'confidential'
   }
})

// Encrypt stream
const fileStream = fs.createReadStream('document.pdf')
const encryptedStream = await client.encrypt(fileStream, 'Documents')

---

decrypt(data: string | Buffer | Readable, privateKey?: string, options?: EncodingOptions): Promise<string | Buffer | Readable>

Decrypts data. The KeyRing used for encryption is automatically determined from the data's header.

Parameters:

Parameter	Type	Required	Description
data	string | Buffer | Readable	Yes	Encrypted data to decrypt
privateKey	string	No	Private key if using customer-managed keys
options	EncodingOptions	No	Encoding options
options.asset	string | object	No	Asset metadata for tracking (optional during decryption)
options.outFormat	EncodingFormat	No	Output format: 'string', 'buffer', or 'readable-stream'
options.inEncoding	Encoding	No	Input data encoding
options.outEncoding	Encoding	No	Output data encoding

Returns: Promise<string | Buffer | Readable> - Decrypted data

Example:

// Decrypt string
const decrypted = await client.decrypt(encryptedData)

// Decrypt with private key (customer-managed keys)
const privateKey = fs.readFileSync('./private.pem', 'utf-8')
const decrypted = await client.decrypt(encryptedData, privateKey)

// Decrypt stream
const encryptedStream = fs.createReadStream('encrypted.bin')
const decryptedStream = await client.decrypt(encryptedStream)

---

KeyRingWarden

Manages KeyRing lifecycle operations. Access via client.ring.

Methods

create(name: string, options?: KeyRingCreateOptions): Promise<IKeyRing>

Creates a new KeyRing with a unique name.

Parameters:

Parameter	Type	Required	Description
name	string	Yes	Unique name for the KeyRing
options	KeyRingCreateOptions	No	Configuration options
options.algo	Algorithm	No	Encryption algorithm (default: 'aes256')
options.publicKey	string	No	PEM-formatted RSA public key
options.privateKey	string	No	PEM-formatted RSA private key
options.config	KeyRingConfig	No	KeyRing configuration
options.config.props	object	No	Additional KeyRing metadata
options.config.key.props	object	No	Metadata for keys created in this KeyRing
options.config.algos.aes256.maxEncryptCount	number	No	Number of encryptions before key rotation

Returns: Promise<IKeyRing> - The created KeyRing

Example:

// Create with defaults
const ring = await client.ring.create('TeamA')

// Create with configuration
const ring = await client.ring.create('Finance', {
   config: {
      props: { team: 'finance', region: 'us-west' },
      algos: {
         aes256: {
            maxEncryptCount: 50000
         }
      }
   }
})

// Create with customer-managed keys
const publicKey = fs.readFileSync('./public.pem', 'utf-8')
const privateKey = fs.readFileSync('./private.pem', 'utf-8')

const ring = await client.ring.create('Secure', {
   publicKey,
   privateKey
})

---

get(name: string): Promise<IKeyRing | undefined>

Retrieves a KeyRing by name.

Parameters:

Parameter	Type	Required	Description
name	string	Yes	KeyRing name

Returns: Promise<IKeyRing | undefined> - The KeyRing, or undefined if not found

Example:

const ring = await client.ring.get('Finance')

if (ring) {
   const encrypted = await ring.encrypt('data')
}

---

getById(id: string): Promise<IKeyRing | undefined>

Retrieves a KeyRing by ID.

Parameters:

Parameter	Type	Required	Description
id	string	Yes	KeyRing ID

Returns: Promise<IKeyRing | undefined> - The KeyRing, or undefined if not found

Example:

const ring = await client.ring.getById('ring-123456')

---

getAll(): Promise<string[]>

Lists all KeyRing names.

Returns: Promise<string[]> - Array of KeyRing names

Example:

const rings = await client.ring.getAll()
console.log(rings)  // ['Finance', 'HR', 'Engineering']

---

delete(name: string): Promise<void>

Deletes a KeyRing. This operation cannot be undone.

Parameters:

Parameter	Type	Required	Description
name	string	Yes	KeyRing name to delete

Returns: Promise<void>

Example:

await client.ring.delete('OldKeyRing')

---

KeyRing

Represents a single KeyRing. Obtained through KeyRingWarden methods.

Properties

id: string (readonly)

The unique identifier for this KeyRing.

name: string (readonly)

The KeyRing name (lowercase).

displayName: string (readonly)

The KeyRing name with original casing preserved.

activeKey: Key (readonly)

The currently active encryption key.

---

Methods

encrypt(data: string | Buffer | Readable, options?: EncodingOptions): Promise<string | Buffer | Readable>

Encrypts data using this KeyRing's active key.

Parameters:

Parameter	Type	Required	Description
data	string | Buffer | Readable	Yes	Data to encrypt
options	EncodingOptions	No	Encoding options
options.asset	string | object	No	Asset metadata (cryptographically signed and embedded in header)
options.outFormat	EncodingFormat	No	Output format
options.inEncoding	Encoding	No	Input encoding
options.outEncoding	Encoding	No	Output encoding

Returns: Promise<string | Buffer | Readable> - Encrypted data

Example:

const ring = await client.ring.get('Finance')

// Encrypt string
const encrypted = await ring.encrypt('Sensitive data')

// Encrypt with Asset metadata
const encrypted = await ring.encrypt('User record', {
   asset: {
      id: 'user-456',
      type: 'user-record',
      department: 'finance'
   }
})

// Encrypt buffer
const buffer = Buffer.from('Binary data')
const encrypted = await ring.encrypt(buffer)

---

decrypt(data: string | Buffer | Readable, options?: EncodingOptions): Promise<string | Buffer | Readable>

Decrypts data that was encrypted with this KeyRing.

Parameters:

Parameter	Type	Required	Description
data	string | Buffer | Readable	Yes	Encrypted data
options	EncodingOptions	No	Encoding options

Returns: Promise<string | Buffer | Readable> - Decrypted data

Example:

const ring = await client.ring.get('Finance')

const decrypted = await ring.decrypt(encryptedData)

---

rotate(algo?: Algorithm): Promise<Key>

Manually rotates the KeyRing's active key. Normally, keys rotate automatically based on configuration.

Parameters:

Parameter	Type	Required	Description
algo	Algorithm	No	Algorithm for new key (default: current algorithm)

Returns: Promise<Key> - The new active key

Example:

const ring = await client.ring.get('Finance')

// Rotate key
await ring.rotate()

// New encryptions use the new key
const encrypted = await ring.encrypt('New data')

// Old data still decrypts with rotated keys
const old = await ring.decrypt(oldEncryptedData)

---

getConfig(): Promise<KeyRingConfig>

Retrieves the current KeyRing configuration.

Returns: Promise<KeyRingConfig> - Current configuration

Example:

const ring = await client.ring.get('Finance')
const config = await ring.getConfig()

console.log(config.algos.aes256.maxEncryptCount)

---

updateConfig(handler: KeyRingConfigUpdateHandler): Promise<void>

Updates the KeyRing configuration.

Parameters:

Parameter	Type	Required	Description
handler	function	Yes	Callback to modify config

Handler signature: (config: KeyRingConfig) => void

Returns: Promise<void>

Example:

const ring = await client.ring.get('Finance')

await ring.updateConfig((config) => {
   config.algos.aes256.maxEncryptCount = 100000
   config.props.team = 'finance-v2'
})

---

Type Definitions

Algorithm

Supported encryption algorithms:

type Algorithm = 'aes256'

EncodingFormat

Output format options:

type EncodingFormat = 'string' | 'buffer' | 'readable-stream'

Encoding

Character encoding options:

type Encoding = 'utf8' | 'ascii' | 'base64' | 'hex' | 'binary' | 'utf16le'

KeyRingConfig

interface KeyRingConfig {
   props?: Record<string, any>
   key?: {
      props?: Record<string, any>
   }
   algos: {
      aes256?: {
         maxEncryptCount: number
      }
   }
}

---

Error Handling

The SDK throws standard JavaScript Error objects. Wrap SDK calls in try-catch blocks:

try {
   const ring = await client.ring.get('Finance')
   const encrypted = await ring.encrypt('data')
} catch (error) {
   console.error('Encryption failed:', error.message)
}

Common error scenarios:

• Authentication failures: Invalid API key or insufficient permissions
• KeyRing not found: Attempting to access non-existent KeyRing
• Network errors: Connection issues with Grizzly instance
• Decryption failures: Invalid encrypted data or missing keys

See Error Handling & Troubleshooting for detailed error resolution.