0
# System Operations
1

2
System-level operations including JWT signing key management and account utilities for configuring and monitoring Mux platform access and security settings.
3

4
## Capabilities
5

6
### JWT Signing Key Management
7

8
Manage JWT signing keys for secure token generation and API access control.
9

10
```typescript { .api }
11
/**
12
 * Create a new JWT signing key
13
 * @returns Promise resolving to the created signing key
14
 */
15
create(): Promise<SigningKey>;
16

17
interface SigningKey {
18
  /** Signing key identifier */
19
  id: string;
20
  /** Base64-encoded private key for JWT signing */
21
  private_key: string;
22
  /** Creation timestamp */
23
  created_at: string;
24
}
25

26
/**
27
 * Retrieve signing key details
28
 * @param signingKeyId - The signing key identifier
29
 * @returns Promise resolving to signing key details
30
 */
31
retrieve(signingKeyId: string): Promise<SigningKey>;
32

33
/**
34
 * List signing keys with pagination
35
 * @param query - Listing parameters
36
 * @returns Paginated list of signing keys
37
 */
38
list(query?: SigningKeyListParams): PagePromise<SigningKeysBasePage, SigningKey>;
39

40
interface SigningKeyListParams extends BasePageParams {
41
  /** Additional filtering options */
42
  [key: string]: any;
43
}
44

45
/**
46
 * Delete a signing key permanently
47
 * @param signingKeyId - The signing key identifier
48
 * @returns Promise that resolves when deletion is complete
49
 */
50
delete(signingKeyId: string): Promise<void>;
51
```
52

53
**Usage Examples:**
54

55
```typescript
56
// Create a new signing key
57
const signingKey = await mux.system.signingKeys.create();
58
console.log('New signing key ID:', signingKey.id);
59

60
// Store the private key securely
61
process.env.MUX_PRIVATE_KEY = signingKey.private_key;
62

63
// List all signing keys
64
const signingKeys = await mux.system.signingKeys.list();
65
console.log(`Total signing keys: ${signingKeys.data.length}`);
66

67
// Retrieve specific signing key
68
const key = await mux.system.signingKeys.retrieve('signing-key-id');
69

70
// Delete old signing key
71
await mux.system.signingKeys.delete('old-signing-key-id');
72
```
73

74
### Account Utilities
75

76
Access account information and token details for debugging and monitoring purposes.
77

78
```typescript { .api }
79
/**
80
 * Get information about the current API token and account
81
 * @returns Promise resolving to token and account information
82
 */
83
whoami(): Promise<UtilityWhoamiResponse>;
84

85
interface UtilityWhoamiResponse {
86
  /** Access token name */
87
  access_token_name: string;
88
  /** Environment identifier */
89
  environment_id: string;
90
  /** Environment name */
91
  environment_name: string;
92
  /** Environment type (production, development, etc) */
93
  environment_type: string;
94
  /** Organization identifier */
95
  organization_id: string;
96
  /** Organization name */
97
  organization_name: string;
98
  /** Token permissions */
99
  permissions: Array<string>;
100
}
101
```
102

103
**Usage Examples:**
104

105
```typescript
106
// Get current token information
107
const info = await mux.system.utilities.whoami();
108
console.log('Organization ID:', info.organization_id);
109
console.log('Environment:', info.environment_name);
110
console.log('Token permissions:', info.permissions);
111

112
// Verify token permissions
113
if (info.permissions.includes('video')) {
114
  console.log('Token has video access');
115
}
116
```
117

118
## Key Management Best Practices
119

120
### Signing Key Rotation
121

122
Implement regular signing key rotation for enhanced security:
123

124
```typescript
125
async function rotateSigningKey() {
126
  // Create new signing key
127
  const newKey = await mux.system.signingKeys.create();
128

129
  // Update environment/configuration with new key
130
  await updateConfiguration({
131
    MUX_SIGNING_KEY: newKey.id,
132
    MUX_PRIVATE_KEY: newKey.private_key,
133
  });
134

135
  // Wait for propagation (allow time for new key to be active)
136
  await new Promise(resolve => setTimeout(resolve, 30000));
137

138
  // List existing keys to find old ones
139
  const keys = await mux.system.signingKeys.list();
140

141
  // Delete keys older than the new one
142
  for (const key of keys.data) {
143
    if (key.id !== newKey.id && new Date(key.created_at) < new Date(newKey.created_at)) {
144
      await mux.system.signingKeys.delete(key.id);
145
      console.log(`Deleted old signing key: ${key.id}`);
146
    }
147
  }
148

149
  console.log(`Signing key rotation complete. New key ID: ${newKey.id}`);
150
}
151

152
// Rotate keys monthly
153
setInterval(rotateSigningKey, 30 * 24 * 60 * 60 * 1000);
154
```
155

156
### Monitoring and Alerts
157

158
Monitor token usage and permissions:
159

160
```typescript
161
async function monitorTokenHealth() {
162
  try {
163
    const info = await mux.system.utilities.whoami();
164

165
    // Verify expected permissions
166
    const requiredPermissions = ['video', 'data'];
167
    const hasPermissions = requiredPermissions.every(perm =>
168
      info.permissions.includes(perm)
169
    );
170

171
    if (!hasPermissions) {
172
      console.error('Token missing required permissions');
173
    }
174

175
    console.log(`Token health check passed for ${info.environment_name}`);
176
    console.log(`Organization: ${info.organization_name}`);
177
  } catch (error) {
178
    console.error('Token health check failed:', error);
179
  }
180
}
181

182
// Check token health hourly
183
setInterval(monitorTokenHealth, 60 * 60 * 1000);
184
```
185

186
### Development vs Production Keys
187

188
Separate signing keys for different environments:
189

190
```typescript
191
async function setupEnvironmentKeys() {
192
  const environments = ['development', 'staging', 'production'];
193

194
  for (const env of environments) {
195
    // Create dedicated signing key for each environment
196
    const key = await mux.system.signingKeys.create();
197

198
    console.log(`${env.toUpperCase()} signing key created:`);
199
    console.log(`  ID: ${key.id}`);
200
    console.log(`  Set MUX_SIGNING_KEY=${key.id}`);
201
    console.log(`  Set MUX_PRIVATE_KEY=${key.private_key}`);
202
    console.log('');
203
  }
204
}
205
```
206

207
### Emergency Key Recovery
208

209
Handle emergency scenarios where keys need to be recreated:
210

211
```typescript
212
async function emergencyKeyRecovery() {
213
  console.log('Starting emergency key recovery...');
214

215
  try {
216
    // Verify current token still works
217
    await mux.system.utilities.whoami();
218
    console.log('Current token is still valid');
219
  } catch (error) {
220
    console.error('Current token is invalid, manual intervention required');
221
    return;
222
  }
223

224
  // Create new signing key immediately
225
  const emergencyKey = await mux.system.signingKeys.create();
226

227
  console.log('Emergency signing key created:');
228
  console.log(`ID: ${emergencyKey.id}`);
229
  console.log(`Private Key: ${emergencyKey.private_key}`);
230

231
  // List and optionally delete compromised keys
232
  const keys = await mux.system.signingKeys.list();
233
  console.log(`Found ${keys.data.length} total signing keys`);
234

235
  // Manual approval needed for deletion in emergency situations
236
  console.log('Review and delete compromised keys manually');
237
}
238
```
239

240
## Error Handling
241

242
```typescript
243
import {
244
  AuthenticationError,
245
  PermissionDeniedError,
246
  NotFoundError
247
} from '@mux/mux-node';
248

249
async function handleSystemOperationErrors() {
250
  try {
251
    const key = await mux.system.signingKeys.create();
252
    console.log('Signing key created successfully');
253
  } catch (error) {
254
    if (error instanceof AuthenticationError) {
255
      console.error('Authentication failed - check token credentials');
256
    } else if (error instanceof PermissionDeniedError) {
257
      console.error('Insufficient permissions to create signing keys');
258
    } else {
259
      console.error('Unexpected error:', error.message);
260
    }
261
  }
262

263
  try {
264
    const info = await mux.system.utilities.whoami();
265
    console.log('Token info retrieved successfully');
266
  } catch (error) {
267
    if (error instanceof NotFoundError) {
268
      console.error('Token not found or invalid');
269
    } else {
270
      console.error('Failed to get token info:', error.message);
271
    }
272
  }
273
}
274
```
275

276
## Types
277

278
```typescript { .api }
279
interface SigningKeyCreateResponse {
280
  /** Created signing key data */
281
  data: SigningKey;
282
}
283

284
interface SigningKeyListResponse {
285
  /** Array of signing keys */
286
  data: Array<SigningKey>;
287
  /** Pagination information */
288
  pagination?: PaginationInfo;
289
}
290

291
interface PaginationInfo {
292
  /** Current page number */
293
  page: number;
294
  /** Number of items per page */
295
  limit: number;
296
  /** Total number of items */
297
  total: number;
298
}
299

300
type TokenType = 'api_token' | 'signing_key';
301

302
interface TokenPermissions {
303
  /** Video asset permissions */
304
  video_assets?: Array<'read' | 'write' | 'delete'>;
305
  /** Live stream permissions */
306
  live_streams?: Array<'read' | 'write' | 'delete'>;
307
  /** Data analytics permissions */
308
  data?: Array<'read'>;
309
  /** System permissions */
310
  system?: Array<'read' | 'write'>;
311
}
312
```