0
# Authentication & Token Management
1

2
The Zoho CRM SDK implements OAuth 2.0 authentication with flexible token storage options, supporting file-based storage, database storage, and custom storage implementations.
3

4
## Capabilities
5

6
### OAuth Token Builder
7

8
Create OAuth tokens for authentication with various configuration options.
9

10
```javascript { .api }
11
/**
12
 * Builder for creating OAuth tokens with different authentication flows
13
 */
14
class OAuthBuilder {
15
    /** Set OAuth client ID */
16
    clientId(clientId: string): OAuthBuilder;
17
    /** Set OAuth client secret */
18
    clientSecret(clientSecret: string): OAuthBuilder;
19
    /** Set refresh token for token refresh flow */
20
    refreshToken(refreshToken: string): OAuthBuilder;
21
    /** Set grant token for initial authorization */
22
    grantToken(grantToken: string): OAuthBuilder;
23
    /** Set access token for direct token usage */
24
    accessToken(accessToken: string): OAuthBuilder;
25
    /** Set OAuth redirect URL */
26
    redirectURL(redirectURL: string): OAuthBuilder;
27
    /** Set unique identifier for token persistence */
28
    id(id: string): OAuthBuilder;
29
    /** Build the OAuth token */
30
    build(): OAuthToken;
31
}
32
```
33

34
**Usage Examples:**
35

36
```javascript
37
const { OAuthBuilder } = require("@zohocrm/nodejs-sdk-2.0/models/authenticator/oauth_builder");
38

39
// Using refresh token (recommended for production)
40
const token = new OAuthBuilder()
41
    .clientId("your_client_id")
42
    .clientSecret("your_client_secret")
43
    .refreshToken("your_refresh_token")
44
    .redirectURL("https://your-app.com/callback")
45
    .build();
46

47
// Using grant token (for initial setup)
48
const grantToken = new OAuthBuilder()
49
    .clientId("your_client_id")
50
    .clientSecret("your_client_secret")
51
    .grantToken("your_grant_token")
52
    .redirectURL("https://your-app.com/callback")
53
    .build();
54

55
// Using access token directly
56
const accessToken = new OAuthBuilder()
57
    .accessToken("your_access_token")
58
    .build();
59

60
// Using stored token ID
61
const storedToken = new OAuthBuilder()
62
    .id("unique_token_id")
63
    .build();
64
```
65

66
### OAuth Token
67

68
The OAuth token implementation with all authentication details.
69

70
```javascript { .api }
71
/**
72
 * OAuth token containing authentication information
73
 */
74
class OAuthToken {
75
    /** Get client ID */
76
    getClientId(): string;
77
    /** Get client secret */
78
    getClientSecret(): string;
79
    /** Get access token */
80
    getAccessToken(): string;
81
    /** Get refresh token */
82
    getRefreshToken(): string;
83
    /** Get redirect URL */
84
    getRedirectURL(): string;
85
    /** Get grant token */
86
    getGrantToken(): string;
87
    /** Get token ID */
88
    getId(): string;
89
    /** Get token expiry time */
90
    getExpiryTime(): string;
91
    /** Set access token */
92
    setAccessToken(accessToken: string): void;
93
    /** Set refresh token */
94
    setRefreshToken(refreshToken: string): void;
95
    /** Set expiry time */
96
    setExpiryTime(expiryTime: string): void;
97
}
98
```
99

100
### Token Storage Interface
101

102
Abstract base class for implementing token persistence strategies.
103

104
```javascript { .api }
105
/**
106
 * Abstract token store for persisting OAuth tokens
107
 */
108
abstract class TokenStore {
109
    /**
110
     * Retrieve a token for a specific user
111
     * @param user - The user signature
112
     * @param token - Token instance for type matching
113
     * @returns The stored token or null if not found
114
     */
115
    getToken(user: UserSignature, token: Token): Promise<Token>;
116

117
    /**
118
     * Save a token for a specific user
119
     * @param user - The user signature
120
     * @param token - The token to save
121
     */
122
    saveToken(user: UserSignature, token: Token): Promise<void>;
123

124
    /**
125
     * Delete a specific token
126
     * @param token - The token to delete
127
     */
128
    deleteToken(token: Token): Promise<void>;
129

130
    /**
131
     * Get all stored tokens
132
     * @returns Array of all tokens
133
     */
134
    getTokens(): Promise<Token[]>;
135

136
    /**
137
     * Delete all stored tokens
138
     */
139
    deleteTokens(): Promise<void>;
140

141
    /**
142
     * Get token by unique identifier
143
     * @param id - Unique token identifier
144
     * @param token - Token instance for type matching
145
     * @returns The token if found
146
     */
147
    getTokenById(id: string, token: Token): Promise<Token>;
148
}
149
```
150

151
### File-Based Token Storage
152

153
Store OAuth tokens in a local file.
154

155
```javascript { .api }
156
/**
157
 * File-based token storage implementation
158
 */
159
class FileStore extends TokenStore {
160
    /**
161
     * Create file store with specified file path
162
     * @param filePath - Absolute path to token storage file
163
     */
164
    constructor(filePath: string);
165

166
    /** Get token from file storage */
167
    getToken(user: UserSignature, token: Token): Promise<Token>;
168
    /** Save token to file storage */
169
    saveToken(user: UserSignature, token: Token): Promise<void>;
170
    /** Delete token from file storage */
171
    deleteToken(token: Token): Promise<void>;
172
    /** Get all tokens from file storage */
173
    getTokens(): Promise<Token[]>;
174
    /** Delete all tokens from file storage */
175
    deleteTokens(): Promise<void>;
176
    /** Get token by ID from file storage */
177
    getTokenById(id: string, token: Token): Promise<Token>;
178
}
179
```
180

181
**File Storage Usage Example:**
182

183
```javascript
184
const { FileStore } = require("@zohocrm/nodejs-sdk-2.0/models/authenticator/store/file_store");
185

186
// Create file store
187
const tokenStore = new FileStore("/Users/username/Documents/zoho_tokens.txt");
188

189
// Use with initialization
190
await new InitializeBuilder()
191
    .user(user)
192
    .environment(environment)
193
    .token(token)
194
    .store(tokenStore)
195
    .initialize();
196
```
197

198
### Database Token Storage
199

200
Store OAuth tokens in a MySQL database with configurable connection settings.
201

202
```javascript { .api }
203
/**
204
 * Database builder for MySQL token storage
205
 */
206
class DBBuilder {
207
    /** Set database host (default: localhost) */
208
    host(host: string): DBBuilder;
209
    /** Set database name (default: zohooauth) */
210
    databaseName(databaseName: string): DBBuilder;
211
    /** Set database username (default: root) */
212
    userName(userName: string): DBBuilder;
213
    /** Set database password (default: empty) */
214
    password(password: string): DBBuilder;
215
    /** Set database port (default: 3306) */
216
    portNumber(portNumber: string): DBBuilder;
217
    /** Set table name (default: oauthtoken) */
218
    tableName(tableName: string): DBBuilder;
219
    /** Build the database store */
220
    build(): DBStore;
221
}
222

223
/**
224
 * Database token storage implementation
225
 */
226
class DBStore extends TokenStore {
227
    /** Get token from database */
228
    getToken(user: UserSignature, token: Token): Promise<Token>;
229
    /** Save token to database */
230
    saveToken(user: UserSignature, token: Token): Promise<void>;
231
    /** Delete token from database */
232
    deleteToken(token: Token): Promise<void>;
233
    /** Get all tokens from database */
234
    getTokens(): Promise<Token[]>;
235
    /** Delete all tokens from database */
236
    deleteTokens(): Promise<void>;
237
    /** Get token by ID from database */
238
    getTokenById(id: string, token: Token): Promise<Token>;
239
}
240
```
241

242
**Database Storage Usage Example:**
243

244
```javascript
245
const { DBBuilder } = require("@zohocrm/nodejs-sdk-2.0/models/authenticator/store/db_builder");
246

247
// Configure database connection
248
const tokenStore = new DBBuilder()
249
    .host("localhost")
250
    .databaseName("zohooauth")
251
    .userName("dbuser")
252
    .password("dbpassword")
253
    .portNumber("3306")
254
    .tableName("oauth_tokens")
255
    .build();
256

257
// Use with initialization
258
await new InitializeBuilder()
259
    .user(user)
260
    .environment(environment)
261
    .token(token)
262
    .store(tokenStore)
263
    .initialize();
264
```
265

266
**Required Database Schema:**
267

268
```sql
269
CREATE TABLE oauthtoken (
270
  id varchar(255) NOT NULL,
271
  user_mail varchar(255) NOT NULL,
272
  client_id varchar(255),
273
  client_secret varchar(255),
274
  refresh_token varchar(255),
275
  access_token varchar(255),
276
  grant_token varchar(255),
277
  expiry_time varchar(20),
278
  redirect_url varchar(255),
279
  primary key (id)
280
);
281
```
282

283
### Custom Token Storage
284

285
Implement custom token storage by extending the TokenStore class.
286

287
```javascript { .api }
288
/**
289
 * Custom token store implementation example
290
 */
291
class CustomStore extends TokenStore {
292
    constructor() {
293
        super();
294
    }
295

296
    /**
297
     * Implement custom token retrieval logic
298
     * @param user - User signature
299
     * @param token - Token instance for type matching
300
     * @returns Stored token or null
301
     */
302
    getToken(user: UserSignature, token: Token): Promise<Token> {
303
        // Custom implementation
304
        return null;
305
    }
306

307
    /**
308
     * Implement custom token saving logic
309
     * @param user - User signature
310
     * @param token - Token to save
311
     */
312
    saveToken(user: UserSignature, token: Token): Promise<void> {
313
        // Custom implementation
314
    }
315

316
    /**
317
     * Implement custom token deletion logic
318
     * @param token - Token to delete
319
     */
320
    deleteToken(token: Token): Promise<void> {
321
        // Custom implementation
322
    }
323

324
    /**
325
     * Implement custom token retrieval for all tokens
326
     * @returns Array of all stored tokens
327
     */
328
    getTokens(): Promise<Token[]> {
329
        // Custom implementation
330
        return [];
331
    }
332

333
    /**
334
     * Implement custom deletion of all tokens
335
     */
336
    deleteTokens(): Promise<void> {
337
        // Custom implementation
338
    }
339

340
    /**
341
     * Implement custom token retrieval by ID
342
     * @param id - Unique token identifier
343
     * @param token - Token instance for type matching
344
     * @returns Token if found
345
     */
346
    getTokenById(id: string, token: Token): Promise<Token> {
347
        // Custom implementation
348
        return null;
349
    }
350
}
351
```
352

353
**Custom Storage Usage Example:**
354

355
```javascript
356
// Implement custom storage (e.g., Redis, MongoDB, etc.)
357
class RedisTokenStore extends TokenStore {
358
    constructor(redisClient) {
359
        super();
360
        this.redis = redisClient;
361
    }
362

363
    async getToken(user, token) {
364
        const key = `zoho_token:${user.getEmail()}`;
365
        const tokenData = await this.redis.get(key);
366
        return tokenData ? JSON.parse(tokenData) : null;
367
    }
368

369
    async saveToken(user, token) {
370
        const key = `zoho_token:${user.getEmail()}`;
371
        await this.redis.set(key, JSON.stringify(token));
372
    }
373

374
    async deleteToken(token) {
375
        // Implementation for specific token deletion
376
    }
377

378
    // ... implement other required methods
379
}
380

381
// Use custom store
382
const customStore = new RedisTokenStore(redisClient);
383

384
await new InitializeBuilder()
385
    .user(user)
386
    .environment(environment)
387
    .token(token)
388
    .store(customStore)
389
    .initialize();
390
```
391

392
### Token Interface
393

394
The base token interface that all token implementations must follow.
395

396
```javascript { .api }
397
/**
398
 * Base token interface
399
 */
400
interface Token {
401
    /** Generate authentication header for API requests */
402
    authenticate(): Promise<void>;
403
    /** Remove authentication token */
404
    remove(): Promise<boolean>;
405
}
406
```