0
# Authentication Tokens
1

2
The Tokens class (accessed via `client.authTokens`) provides methods for creating ephemeral authentication tokens for use with constrained API access, particularly for Live API sessions. These tokens allow you to control access to Live API connections with specific constraints and expiration times.
3

4
**Note**: This feature is experimental and only supported in the Gemini Developer API (not Vertex AI), using API version `v1alpha`.
5

6
## Capabilities
7

8
### Create Authentication Token
9

10
Creates an ephemeral authentication token that can be used for secure, constrained access to Live API sessions. Tokens can be configured to lock specific fields in LiveConnectConfig, limiting what session configurations can be modified when the token is used.
11

12
```typescript { .api }
13
/**
14
 * Creates an ephemeral auth token resource
15
 * @experimental
16
 * @param params - Parameters for creating the auth token
17
 * @returns Promise resolving to the created AuthToken
18
 * @throws Error if called on a Vertex AI client
19
 * @remarks Only supported in v1alpha API version of the Gemini Developer API
20
 */
21
function create(params: CreateAuthTokenParameters): Promise<AuthToken>;
22

23
interface CreateAuthTokenParameters {
24
  config?: CreateAuthTokenConfig;
25
}
26

27
interface CreateAuthTokenConfig {
28
  uses?: number;
29
  expireTime?: string;
30
  bidiGenerateContentSetup?: LiveConnectConstraints;
31
  lockAdditionalFields?: string[];
32
  httpOptions?: HttpOptions;
33
  abortSignal?: AbortSignal;
34
}
35

36
interface AuthToken {
37
  name?: string;
38
  uses?: number;
39
  expireTime?: string;
40
  usesRemaining?: number;
41
  createTime?: string;
42
}
43
```
44

45
## Token Configuration Modes
46

47
Authentication tokens support multiple configuration modes that control which Live API connection parameters can be modified when using the token.
48

49
### Mode 1: Unlocked Configuration
50

51
If `bidiGenerateContentSetup` is unset, the token allows full flexibility in LiveConnectConfig for each session connection.
52

53
```typescript
54
import { GoogleGenAI } from '@google/genai';
55

56
const client = new GoogleGenAI({
57
  apiKey: 'YOUR_API_KEY',
58
  httpOptions: { apiVersion: 'v1alpha' }  // Required for auth tokens
59
});
60

61
// Create token with unlocked configuration
62
const token = await client.authTokens.create({
63
  config: {
64
    uses: 3,
65
    expireTime: '2025-05-01T00:00:00Z'
66
  }
67
});
68

69
console.log('Token created:', token.name);
70
console.log('Uses remaining:', token.usesRemaining);
71

72
// Use the token to connect to Live API with any configuration
73
const sessionClient = new GoogleGenAI({
74
  apiKey: token.name,
75
  httpOptions: { apiVersion: 'v1alpha' }
76
});
77

78
const session = await sessionClient.live.connect({
79
  model: 'gemini-2.0-flash',
80
  config: {
81
    responseModalities: ['AUDIO'],
82
    systemInstruction: 'Be helpful and concise'
83
    // Any configuration can be used
84
  }
85
});
86
```
87

88
### Mode 2: Fully Locked Configuration
89

90
If `bidiGenerateContentSetup` is set, all fields in LiveConnectConfig are locked to the values specified in the setup. Attempts to change these fields when connecting will be ignored by the API.
91

92
```typescript
93
// Create token with locked configuration
94
const token = await client.authTokens.create({
95
  config: {
96
    uses: 3,
97
    expireTime: '2025-05-01T00:00:00Z',
98
    bidiGenerateContentSetup: {
99
      setup: {
100
        model: 'gemini-2.0-flash',
101
        generationConfig: {
102
          responseModalities: ['AUDIO'],
103
          temperature: 0.7
104
        },
105
        systemInstruction: {
106
          parts: [{ text: 'Always answer in English.' }]
107
        }
108
      }
109
    }
110
  }
111
});
112

113
// When using this token, all config fields are locked
114
const sessionClient = new GoogleGenAI({
115
  apiKey: token.name,
116
  httpOptions: { apiVersion: 'v1alpha' }
117
});
118

119
const session = await sessionClient.live.connect({
120
  model: 'gemini-2.0-flash',  // Locked - cannot be changed
121
  config: {
122
    responseModalities: ['TEXT'],  // Ignored - locked to ['AUDIO']
123
    temperature: 1.0,              // Ignored - locked to 0.7
124
    systemInstruction: 'Speak Spanish'  // Ignored - locked to English
125
  }
126
});
127
```
128

129
### Mode 3: Partially Locked with Additional Fields
130

131
If `bidiGenerateContentSetup` is set along with `lockAdditionalFields`, the specified fields from setup are locked, plus any additional fields listed in `lockAdditionalFields`.
132

133
```typescript
134
// Create token with setup fields + additional locked fields
135
const token = await client.authTokens.create({
136
  config: {
137
    uses: 3,
138
    expireTime: '2025-05-01T00:00:00Z',
139
    bidiGenerateContentSetup: {
140
      setup: {
141
        model: 'gemini-2.0-flash',
142
        generationConfig: {
143
          responseModalities: ['AUDIO'],
144
          systemInstruction: {
145
            parts: [{ text: 'Always answer in English.' }]
146
          }
147
        }
148
      }
149
    },
150
    lockAdditionalFields: ['temperature', 'topK']
151
  }
152
});
153

154
// When connecting:
155
// - model: locked to 'gemini-2.0-flash'
156
// - responseModalities: locked to ['AUDIO']
157
// - systemInstruction: locked to 'Always answer in English.'
158
// - temperature: locked (cannot be modified)
159
// - topK: locked (cannot be modified)
160
// - Other fields like topP, maxOutputTokens can still be modified
161
```
162

163
### Mode 4: Only Setup Fields Locked
164

165
If `bidiGenerateContentSetup` is set and `lockAdditionalFields` is an empty array, only the fields explicitly set in the setup are locked.
166

167
```typescript
168
// Create token locking only specified setup fields
169
const token = await client.authTokens.create({
170
  config: {
171
    uses: 3,
172
    expireTime: '2025-05-01T00:00:00Z',
173
    bidiGenerateContentSetup: {
174
      setup: {
175
        model: 'gemini-2.0-flash',
176
        generationConfig: {
177
          responseModalities: ['AUDIO'],
178
          systemInstruction: {
179
            parts: [{ text: 'Always answer in English.' }]
180
          }
181
        }
182
      }
183
    },
184
    lockAdditionalFields: []  // Empty array means lock only setup fields
185
  }
186
});
187

188
// When connecting:
189
// - model: locked to 'gemini-2.0-flash'
190
// - responseModalities: locked to ['AUDIO']
191
// - systemInstruction: locked to 'Always answer in English.'
192
// - temperature, topK, topP, maxOutputTokens, etc. can be freely modified
193
```
194

195
## Token Management
196

197
### Token Expiration
198

199
Tokens expire based on the `expireTime` parameter. After expiration, the token can no longer be used to create sessions.
200

201
```typescript
202
const token = await client.authTokens.create({
203
  config: {
204
    uses: 10,
205
    expireTime: '2025-12-31T23:59:59Z'  // Token expires at end of 2025
206
  }
207
});
208

209
// Check token details
210
console.log('Token expires:', token.expireTime);
211
console.log('Uses remaining:', token.usesRemaining);
212
```
213

214
### Usage Limits
215

216
Tokens have a maximum number of uses specified by the `uses` parameter. Once the token has been used that many times, it cannot create new sessions.
217

218
```typescript
219
const token = await client.authTokens.create({
220
  config: {
221
    uses: 5,  // Token can be used for 5 session connections
222
    expireTime: '2025-12-31T23:59:59Z'
223
  }
224
});
225

226
// Each session connection decrements usesRemaining
227
for (let i = 0; i < 3; i++) {
228
  const sessionClient = new GoogleGenAI({
229
    apiKey: token.name,
230
    httpOptions: { apiVersion: 'v1alpha' }
231
  });
232

233
  const session = await sessionClient.live.connect({
234
    model: 'gemini-2.0-flash',
235
    config: { responseModalities: ['AUDIO'] }
236
  });
237

238
  console.log(`Session ${i + 1} created`);
239
  session.close();
240
}
241

242
// Token now has 2 uses remaining
243
```
244

245
## Type Definitions
246

247
```typescript { .api }
248
interface LiveConnectConstraints {
249
  setup?: LiveConnectConstraintsSetup;
250
}
251

252
interface LiveConnectConstraintsSetup {
253
  model?: string;
254
  generationConfig?: LiveConnectConstraintsGenerationConfig;
255
  systemInstruction?: Content;
256
  tools?: Tool[];
257
}
258

259
interface LiveConnectConstraintsGenerationConfig {
260
  temperature?: number;
261
  topK?: number;
262
  topP?: number;
263
  maxOutputTokens?: number;
264
  responseModalities?: Modality[];
265
  seed?: number;
266
  speechConfig?: SpeechConfig;
267
}
268
```
269

270
## Use Cases
271

272
### Temporary Access for External Services
273

274
Create tokens for external services to access your Live API without sharing your main API key.
275

276
```typescript
277
// Create a token for a third-party service
278
const token = await client.authTokens.create({
279
  config: {
280
    uses: 100,
281
    expireTime: '2025-06-01T00:00:00Z',
282
    bidiGenerateContentSetup: {
283
      setup: {
284
        model: 'gemini-2.0-flash',
285
        generationConfig: {
286
          responseModalities: ['AUDIO'],
287
          temperature: 0.8
288
        }
289
      }
290
    }
291
  }
292
});
293

294
// Share token.name with the external service
295
// They can use it without knowing your main API key
296
console.log('Token for external service:', token.name);
297
```
298

299
### Rate-Limited Client Access
300

301
Provide rate-limited access to different client applications.
302

303
```typescript
304
// Create tokens for different clients with different limits
305
const clientAToken = await client.authTokens.create({
306
  config: {
307
    uses: 1000,  // Premium client
308
    expireTime: '2025-12-31T23:59:59Z'
309
  }
310
});
311

312
const clientBToken = await client.authTokens.create({
313
  config: {
314
    uses: 100,  // Free tier client
315
    expireTime: '2025-12-31T23:59:59Z'
316
  }
317
});
318

319
console.log('Premium client token:', clientAToken.name);
320
console.log('Free tier token:', clientBToken.name);
321
```
322

323
### Constrained Demo Applications
324

325
Create tokens with locked configurations for demo or testing purposes.
326

327
```typescript
328
// Token for demo app with fixed, safe configuration
329
const demoToken = await client.authTokens.create({
330
  config: {
331
    uses: 50,
332
    expireTime: '2025-03-01T00:00:00Z',
333
    bidiGenerateContentSetup: {
334
      setup: {
335
        model: 'gemini-2.0-flash',
336
        generationConfig: {
337
          responseModalities: ['AUDIO'],
338
          temperature: 0.5,  // Conservative temperature
339
          maxOutputTokens: 1000  // Limit output length
340
        },
341
        systemInstruction: {
342
          parts: [{
343
            text: 'You are a demo assistant. Keep responses brief and appropriate.'
344
          }]
345
        }
346
      }
347
    }
348
  }
349
});
350

351
console.log('Demo token:', demoToken.name);
352
```
353

354
## API Version Requirement
355

356
**Important**: Authentication tokens are only supported in the `v1alpha` API version. You must specify this version in your client configuration:
357

358
```typescript
359
const client = new GoogleGenAI({
360
  apiKey: 'YOUR_API_KEY',
361
  httpOptions: {
362
    apiVersion: 'v1alpha'  // Required for auth tokens
363
  }
364
});
365
```
366

367
## Platform Availability
368

369
- **Gemini Developer API**: Supported (v1alpha only)
370
- **Vertex AI**: Not supported - will throw an error if attempted
371