0
# Authentication & Security
1

2
Authentication methods and TLS/SSL certificate configuration for secure communications, including basic authentication, bearer tokens, and client certificate handling.
3

4
## Capabilities
5

6
### Authentication
7

8
Methods for setting various authentication schemes.
9

10
```javascript { .api }
11
/**
12
 * Set authentication credentials
13
 * @param {string} user - Username or token
14
 * @param {string} [password] - Password (optional for bearer auth)
15
 * @param {object} [options] - Authentication options
16
 * @param {string} [options.type] - Authentication type: 'basic' or 'bearer'
17
 * @returns {Request} Request instance for chaining
18
 */
19
Request.prototype.auth(user, password?, options?): Request;
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
const superagent = require('superagent');
26

27
// Basic authentication
28
superagent
29
  .get('https://api.example.com/protected')
30
  .auth('username', 'password');
31

32
// Basic auth with colon syntax
33
superagent
34
  .get('https://api.example.com/protected')
35
  .auth('username:password');
36

37
// Bearer token authentication
38
superagent
39
  .get('https://api.example.com/protected')
40
  .auth('token123', { type: 'bearer' });
41

42
// Equivalent bearer token using header
43
superagent
44
  .get('https://api.example.com/protected')
45
  .set('Authorization', 'Bearer token123');
46

47
// Basic auth with only username (empty password)
48
superagent
49
  .get('https://api.example.com/protected')
50
  .auth('username');
51
```
52

53
### TLS/SSL Certificate Configuration
54

55
Methods for configuring client certificates and certificate authorities.
56

57
```javascript { .api }
58
/**
59
 * Set certificate authority (CA) certificate
60
 * @param {Buffer|Buffer[]|string} cert - CA certificate(s)
61
 * @returns {Request} Request instance for chaining
62
 */
63
Request.prototype.ca(cert): Request;
64

65
/**
66
 * Set client private key
67
 * @param {Buffer|string} key - Private key
68
 * @returns {Request} Request instance for chaining
69
 */
70
Request.prototype.key(key): Request;
71

72
/**
73
 * Set client certificate
74
 * @param {Buffer|string} cert - Client certificate
75
 * @returns {Request} Request instance for chaining
76
 */
77
Request.prototype.cert(cert): Request;
78

79
/**
80
 * Set PFX or PKCS12 certificate
81
 * @param {Buffer|string|object} pfx - PFX certificate or options object
82
 * @param {Buffer|string} [pfx.pfx] - PFX certificate data
83
 * @param {string} [pfx.passphrase] - Certificate passphrase
84
 * @returns {Request} Request instance for chaining
85
 */
86
Request.prototype.pfx(pfx): Request;
87

88
/**
89
 * Disable TLS certificate validation (insecure)
90
 * @returns {Request} Request instance for chaining
91
 */
92
Request.prototype.disableTLSCerts(): Request;
93
```
94

95
**Usage Examples:**
96

97
```javascript
98
const fs = require('fs');
99

100
// Set CA certificate
101
const caCert = fs.readFileSync('ca-cert.pem');
102
superagent
103
  .get('https://secure.example.com/api')
104
  .ca(caCert);
105

106
// Multiple CA certificates
107
const caCerts = [
108
  fs.readFileSync('ca-cert1.pem'),
109
  fs.readFileSync('ca-cert2.pem')
110
];
111
superagent
112
  .get('https://secure.example.com/api')
113
  .ca(caCerts);
114

115
// Client certificate authentication
116
const clientKey = fs.readFileSync('client-key.pem');
117
const clientCert = fs.readFileSync('client-cert.pem');
118
superagent
119
  .get('https://secure.example.com/api')
120
  .key(clientKey)
121
  .cert(clientCert);
122

123
// PFX certificate with passphrase
124
const pfxData = fs.readFileSync('certificate.p12');
125
superagent
126
  .get('https://secure.example.com/api')
127
  .pfx({
128
    pfx: pfxData,
129
    passphrase: 'secret123'
130
  });
131

132
// PFX certificate without passphrase
133
superagent
134
  .get('https://secure.example.com/api')
135
  .pfx(pfxData);
136

137
// Disable certificate validation (NOT recommended for production)
138
superagent
139
  .get('https://self-signed.example.com/api')
140
  .disableTLSCerts();
141
```
142

143
### Connection Security
144

145
Additional security-related connection options.
146

147
```javascript { .api }
148
/**
149
 * Enable or disable HTTP/2 for the request (Node.js only)
150
 * @param {boolean} [enabled=true] - Whether to use HTTP/2
151
 * @returns {Request} Request instance for chaining
152
 */
153
Request.prototype.http2(enabled?): Request;
154

155
/**
156
 * Trust localhost certificates (Node.js only)
157
 * @param {boolean} [enabled=true] - Whether to trust localhost certificates
158
 * @returns {Request} Request instance for chaining
159
 */
160
Request.prototype.trustLocalhost(enabled?): Request;
161

162
/**
163
 * Override DNS resolution for specific hostnames
164
 * @param {string|object} override - IP address or hostname mapping object
165
 * @returns {Request} Request instance for chaining
166
 */
167
Request.prototype.connect(override): Request;
168
```
169

170
**Usage Examples:**
171

172
```javascript
173
// Enable HTTP/2 for request
174
superagent
175
  .get('https://api.example.com/data')
176
  .http2();
177

178
// Explicitly disable HTTP/2
179
superagent
180
  .get('https://api.example.com/data')
181
  .http2(false);
182

183
// Trust localhost certificates for development
184
superagent
185
  .get('https://localhost:3000/api')
186
  .trustLocalhost();
187

188
// Don't trust localhost certificates
189
superagent
190
  .get('https://localhost:3000/api')
191
  .trustLocalhost(false);
192

193
// Override DNS for specific hostname
194
superagent
195
  .get('https://api.example.com/data')
196
  .connect('127.0.0.1'); // Connect to localhost instead
197

198
// Override multiple hostnames
199
superagent
200
  .get('https://api.example.com/data')
201
  .connect({
202
    'api.example.com': '192.168.1.100',
203
    'cdn.example.com': '192.168.1.101'
204
  });
205

206
// Wildcard override (all hostnames)
207
superagent
208
  .get('https://any-hostname.com/api')
209
  .connect({ '*': '127.0.0.1' });
210
```
211

212
### Agent Configuration
213

214
HTTP agent configuration for connection pooling and security settings.
215

216
```javascript { .api }
217
/**
218
 * Set HTTP agent for connection pooling
219
 * @param {http.Agent|https.Agent|boolean} agent - HTTP agent or false to disable
220
 * @returns {Request} Request instance for chaining
221
 */
222
Request.prototype.agent(agent): Request;
223

224
/**
225
 * Set custom DNS lookup function
226
 * @param {function} lookup - Custom DNS lookup function
227
 * @returns {Request} Request instance for chaining
228
 */
229
Request.prototype.lookup(lookup): Request;
230
```
231

232
**Usage Examples:**
233

234
```javascript
235
const https = require('https');
236

237
// Custom HTTPS agent with specific options
238
const httpsAgent = new https.Agent({
239
  keepAlive: true,
240
  maxSockets: 10,
241
  ca: fs.readFileSync('ca-cert.pem')
242
});
243

244
superagent
245
  .get('https://api.example.com/data')
246
  .agent(httpsAgent);
247

248
// Disable agent (no connection pooling)
249
superagent
250
  .get('https://api.example.com/data')
251
  .agent(false);
252

253
// Custom DNS lookup
254
const dns = require('dns');
255
superagent
256
  .get('https://api.example.com/data')
257
  .lookup((hostname, options, callback) => {
258
    // Custom DNS resolution logic
259
    dns.lookup(hostname, options, callback);
260
  });
261
```
262

263
## Security Best Practices
264

265
### Certificate Validation
266

267
Always validate certificates in production:
268

269
```javascript
270
// ✅ Good - validates certificates
271
superagent.get('https://api.example.com/data');
272

273
// ❌ Bad - disables certificate validation
274
superagent.get('https://api.example.com/data').disableTLSCerts();
275
```
276

277
### Authentication Token Storage
278

279
Store authentication tokens securely:
280

281
```javascript
282
// ✅ Good - using environment variables
283
const token = process.env.API_TOKEN;
284
superagent
285
  .get('https://api.example.com/data')
286
  .auth(token, { type: 'bearer' });
287

288
// ❌ Bad - hardcoded token
289
superagent
290
  .get('https://api.example.com/data')
291
  .auth('hardcoded-token-123', { type: 'bearer' });
292
```
293

294
### HTTPS Usage
295

296
Always use HTTPS for sensitive data:
297

298
```javascript
299
// ✅ Good - HTTPS
300
superagent.post('https://api.example.com/login').send(credentials);
301

302
// ❌ Bad - HTTP for sensitive data
303
superagent.post('http://api.example.com/login').send(credentials);
304
```