אסימונים זמניים הם אסימוני אימות לטווח קצר שמאפשרים גישה ל-Gemini API דרך WebSockets. הם נועדו לשפר את האבטחה כשמתחברים ישירות ממכשיר של משתמש ל-API (הטמעה של לקוח לשרת). בדומה למפתחות API רגילים, אפשר לחלץ טוקנים זמניים מאפליקציות בצד הלקוח, כמו דפדפני אינטרנט או אפליקציות לנייד. אבל מכיוון שתוקף האסימונים הזמניים פג במהירות ואפשר להגביל אותם, הם מפחיתים באופן משמעותי את סיכוני האבטחה בסביבת ייצור.
איך פועלים טוקנים זמניים
כך פועלים טוקנים זמניים ברמה גבוהה:
הלקוח (לדוגמה, אפליקציית אינטרנט) עובר אימות עם ה-Backend.
הקצה העורפי שולח את האסימון ללקוח לחיבורי WebSocket ל-Live
API. כדי לעשות את זה, צריך להחליף את מפתח ה-API באסימון זמני.
לאחר מכן הלקוח משתמש באסימון כאילו היה מפתח API.
השימוש באסימון משפר את האבטחה, כי גם אם הוא נשלף, תוקף האסימון קצר, בניגוד למפתח API לטווח ארוך שמוטמע בצד הלקוח. מכיוון שהלקוח שולח נתונים ישירות ל-Gemini, זה גם משפר את זמן האחזור ומונע את הצורך בשרתי קצה עורפיים (back-end) שיעבירו את הנתונים בזמן אמת.
יצירת טוקן זמני
הנה דוגמה פשוטה לאופן קבלת טוקן זמני מ-Gemini.
כברירת מחדל, יש לכם דקה אחת להתחיל סשנים חדשים של Live API באמצעות האסימון מהבקשה הזו (newSessionExpireTime), ו-30 דקות לשלוח הודעות דרך החיבור הזה (expireTime).
Python
importdatetimenow=datetime.datetime.now(tz=datetime.timezone.utc)client=genai.Client(http_options={'api_version':'v1alpha',})token=client.auth_tokens.create(config={'uses':1,# The ephemeral token can only be used to start a single session'expire_time':now+datetime.timedelta(minutes=30),# Default is 30 minutes in the future# 'expire_time': '2025-05-17T00:00:00Z', # Accepts isoformat.'new_session_expire_time':now+datetime.timedelta(minutes=1),# Default 1 minute in the future'http_options':{'api_version':'v1alpha'},})# You'll need to pass the value under token.name back to your client to use it
JavaScript
import{GoogleGenAI}from"@google/genai";constclient=newGoogleGenAI({});constexpireTime=newDate(Date.now()+30*60*1000).toISOString();consttoken:AuthToken=awaitclient.authTokens.create({config:{uses:1,// The defaultexpireTime:expireTime// Default is 30 minsnewSessionExpireTime:newDate(Date.now()+(1*60*1000)),// Default 1 minute in the futurehttpOptions:{apiVersion:'v1alpha'},},});
למידע על אילוצים, ערכי ברירת מחדל ומפרטים אחרים של השדה expireTime, אפשר לעיין בהפניית ה-API.
במהלך expireTime הזמן הזה, תצטרכו sessionResumption להתחבר מחדש לשיחה כל 10 דקות (אפשר לעשות זאת עם אותו אסימון גם אם uses: 1).
אפשר גם לנעול טוקן זמני לקבוצה של הגדרות. האפשרות הזו יכולה להיות שימושית לשיפור נוסף של האבטחה של האפליקציה ולשמירה על הוראות המערכת בצד השרת.
Python
client=genai.Client(http_options={'api_version':'v1alpha',})token=client.auth_tokens.create(config={'uses':1,'live_connect_constraints':{'model':'gemini-2.0-flash-live-001','config':{'session_resumption':{},'temperature':0.7,'response_modalities':['TEXT']}},'http_options':{'api_version':'v1alpha'},})# You'll need to pass the value under token.name back to your client to use it
JavaScript
import{GoogleGenAI}from"@google/genai";constclient=newGoogleGenAI({});constexpireTime=newDate(Date.now()+30*60*1000).toISOString();consttoken=awaitclient.authTokens.create({config:{uses:1,// The defaultexpireTime:expireTime,liveConnectConstraints:{model:'gemini-2.0-flash-live-001',config:{sessionResumption:{},temperature:0.7,responseModalities:['TEXT']}},httpOptions:{apiVersion:'v1alpha'}}});// You'll need to pass the value under token.name back to your client to use it
אחרי שמקבלים אסימון זמני, משתמשים בו כאילו היה מפתח API (אבל חשוב לזכור שהוא פועל רק עם ה-API הפעיל, ורק עם גרסה v1alpha של ה-API).
שימו לב: השימוש בטוקנים זמניים מוסיף ערך רק כשפורסים אפליקציות שפועלות לפי גישת הטמעה מצד הלקוח לצד השרת.
JavaScript
import{GoogleGenAI,Modality}from'@google/genai';// Use the token generated in the "Create an ephemeral token" section hereconstai=newGoogleGenAI({apiKey:token.name});constmodel='gemini-2.0-flash-live-001';constconfig={responseModalities:[Modality.TEXT]};asyncfunctionmain(){constsession=awaitai.live.connect({model:model,config:config,callbacks:{...},});// Send content...session.close();}main();
[[["התוכן קל להבנה","easyToUnderstand","thumb-up"],["התוכן עזר לי לפתור בעיה","solvedMyProblem","thumb-up"],["סיבה אחרת","otherUp","thumb-up"]],[["חסרים לי מידע או פרטים","missingTheInformationINeed","thumb-down"],["התוכן מורכב מדי או עם יותר מדי שלבים","tooComplicatedTooManySteps","thumb-down"],["התוכן לא עדכני","outOfDate","thumb-down"],["בעיה בתרגום","translationIssue","thumb-down"],["בעיה בדוגמאות/בקוד","samplesCodeIssue","thumb-down"],["סיבה אחרת","otherDown","thumb-down"]],["עדכון אחרון: 2025-08-22 (שעון UTC)."],[],[],null,["# Ephemeral tokens are short-lived authentication tokens for accessing the Gemini\nAPI through [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API). They are designed to enhance security when\nyou are connecting directly from a user's device to the API (a\n[client-to-server](/gemini-api/docs/live#implementation-approach)\nimplementation). Like standard API keys, ephemeral tokens can be extracted from\nclient-side applications such as web browsers or mobile apps. But because\nephemeral tokens expire quickly and can be restricted, they significantly reduce\nthe security risks in a production environment.\n| **Note:** Ephemeral tokens are only compatible with [Live API](/gemini-api/docs/live) at this time. You should use them when accessing the Live API directly from client-side applications to enhance API key security.\n\nHow ephemeral tokens work\n-------------------------\n\nHere's how ephemeral tokens work at a high level:\n\n1. Your client (e.g. web app) authenticates with your backend.\n2. Your backend requests an ephemeral token from Gemini API's provisioning service.\n3. Gemini API issues a short-lived token.\n4. Your backend sends the token to the client for WebSocket connections to Live API. You can do this by swapping your API key with an ephemeral token.\n5. The client then uses the token as if it were an API key.\n\nThis enhances security because even if extracted, the token is short-lived,\nunlike a long-lived API key deployed client-side. Since the client sends data\ndirectly to Gemini, this also improves latency and avoids your backends needing\nto proxy the real time data.\n\nCreate an ephemeral token\n-------------------------\n\nHere is a simplified example of how to get an ephemeral token from Gemini.\nBy default, you'll have 1 minute to start new Live API sessions using the token\nfrom this request (`newSessionExpireTime`), and 30 minutes to send messages over\nthat connection (`expireTime`). \n\n### Python\n\n import datetime\n\n now = datetime.datetime.now(tz=datetime.timezone.utc)\n\n client = genai.Client(\n http_options={'api_version': 'v1alpha',}\n )\n\n token = client.auth_tokens.create(\n config = {\n 'uses': 1, # The ephemeral token can only be used to start a single session\n 'expire_time': now + datetime.timedelta(minutes=30), # Default is 30 minutes in the future\n # 'expire_time': '2025-05-17T00:00:00Z', # Accepts isoformat.\n 'new_session_expire_time': now + datetime.timedelta(minutes=1), # Default 1 minute in the future\n 'http_options': {'api_version': 'v1alpha'},\n }\n )\n\n # You'll need to pass the value under token.name back to your client to use it\n\n### JavaScript\n\n import { GoogleGenAI } from \"@google/genai\";\n\n const client = new GoogleGenAI({});\n const expireTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();\n\n const token: AuthToken = await client.authTokens.create({\n config: {\n uses: 1, // The default\n expireTime: expireTime // Default is 30 mins\n newSessionExpireTime: new Date(Date.now() + (1 * 60 * 1000)), // Default 1 minute in the future\n httpOptions: {apiVersion: 'v1alpha'},\n },\n });\n\nFor `expireTime` value constraints, defaults, and other field specs, see the\n[API reference](https://ai.google.dev/api/live#ephemeral-auth-tokens).\nWithin the `expireTime` timeframe, you'll need\n[`sessionResumption`](/gemini-api/docs/live-session#session-resumption) to\nreconnect the call every 10 minutes (this can be done with the same token even\nif `uses: 1`).\n\nIt's also possible to lock an ephemeral token to a set of configurations. This\nmight be useful to further improve security of your application and keep your\nsystem instructions on the server side. \n\n### Python\n\n client = genai.Client(\n http_options={'api_version': 'v1alpha',}\n )\n\n token = client.auth_tokens.create(\n config = {\n 'uses': 1,\n 'live_connect_constraints': {\n 'model': 'gemini-2.0-flash-live-001',\n 'config': {\n 'session_resumption':{},\n 'temperature':0.7,\n 'response_modalities':['TEXT']\n }\n },\n 'http_options': {'api_version': 'v1alpha'},\n }\n )\n\n # You'll need to pass the value under token.name back to your client to use it\n\n### JavaScript\n\n import { GoogleGenAI } from \"@google/genai\";\n\n const client = new GoogleGenAI({});\n const expireTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();\n\n const token = await client.authTokens.create({\n config: {\n uses: 1, // The default\n expireTime: expireTime,\n liveConnectConstraints: {\n model: 'gemini-2.0-flash-live-001',\n config: {\n sessionResumption: {},\n temperature: 0.7,\n responseModalities: ['TEXT']\n }\n },\n httpOptions: {\n apiVersion: 'v1alpha'\n }\n }\n });\n\n // You'll need to pass the value under token.name back to your client to use it\n\nYou can also lock a subset of fields, see the [SDK documentation](https://googleapis.github.io/python-genai/genai.html#genai.types.CreateAuthTokenConfig.lock_additional_fields)\nfor more info.\n\nConnect to Live API with an ephemeral token\n-------------------------------------------\n\nOnce you have an ephemeral token, you use it as if it were an API key (but\nremember, it only works for the live API, and only with the `v1alpha` version of\nthe API).\n\nNote that use of ephemeral tokens only adds value when deploying applications\nthat follow [client-to-server implementation](/gemini-api/docs/live#implementation-approach) approach. \n\n### JavaScript\n\n import { GoogleGenAI, Modality } from '@google/genai';\n\n // Use the token generated in the \"Create an ephemeral token\" section here\n const ai = new GoogleGenAI({\n apiKey: token.name\n });\n const model = 'gemini-2.0-flash-live-001';\n const config = { responseModalities: [Modality.TEXT] };\n\n async function main() {\n\n const session = await ai.live.connect({\n model: model,\n config: config,\n callbacks: { ... },\n });\n\n // Send content...\n\n session.close();\n }\n\n main();\n\n| **Note:** If not using the SDK, note that ephemeral tokens must either be passed in an `access_token` query parameter, or in an HTTP `Authorization` prefixed by the [auth-scheme](https://datatracker.ietf.org/doc/html/rfc7235#section-2.1) `Token`.\n\nSee [Get started with Live API](/gemini-api/docs/live) for more examples.\n\nBest practices\n--------------\n\n- Set a short expiration duration using the `expire_time` parameter.\n- Tokens expire, requiring re-initiation of the provisioning process.\n- Verify secure authentication for your own backend. Ephemeral tokens will only be as secure as your backend authentication method.\n- Generally, avoid using ephemeral tokens for backend-to-Gemini connections, as this path is typically considered secure.\n\nLimitations\n-----------\n\nEphemeral tokens are only compatible with [Live API](/gemini-api/docs/live) at this time.\n\nWhat's next\n-----------\n\n- Read the Live API [reference](https://ai.google.dev/api/live#ephemeral-auth-tokens) on ephemeral tokens for more information."]]