Service: Ephemeral Token Service - EyevinnOSC/community GitHub Wiki

Ephemeral Token Service

Ephemeral Token Service (source, serviceId eyevinn-ephtoken-svc) creates short-lived API tokens for the OpenAI Realtime API, so browser and mobile apps can connect directly to OpenAI without shipping your permanent OpenAI API key to the client. Service page: https://app.osaas.io/dashboard/service/eyevinn-ephtoken-svc. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance. License: MIT.

What it can do

  • Issue an ephemeral OpenAI Realtime client token from a /session endpoint.
  • Keep the permanent OpenAI API key on the server side only.

Creating an instance

You need an OpenAI API key with access to the Realtime API. The service has no dependencies on other OSC services.

  1. Store the key with create-service-secret (serviceId eyevinn-ephtoken-svc, for example name openaikey).
  2. Create the instance with create-service-instance, serviceId: "eyevinn-ephtoken-svc":
{ "name": "mytokens", "OpenAiApiKey": "{{secrets.openaikey}}" }
  1. Wait for it to be running (wait-for-service-ready or get-instance-status) and get the URL with describe-service-instance.

Options

Option Required Type Meaning
name Yes string Name of the instance. Letters, digits and underscore only (^\w+$), at most 20 characters.
OpenAiApiKey Yes string, sensitive OpenAI API key used by the service to create Realtime sessions. Store it as a service secret and pass it as {{secrets.NAME}} (whole field value only).

Overwriting a secret does not restart a running instance.

Using the instance

The service has no default admin user and no web UI. Call the /session endpoint to get a token:

curl https://<tenant>-mytokens.eyevinn-ephtoken-svc.auto.prod-se.osaas.io/session

The response contains a client_secret with the token value and its expiry time (Unix timestamp):

{
  "client_secret": {
    "value": "ek_...",
    "expires_at": 1761200000
  }
}

If OpenAI rejects the request, the service returns HTTP 500 with { "message": "..." }. A GET / request returns a plain-text greeting and can be used as a health check.

Fetch a token from your backend or browser and use it as the bearer credential when opening a Realtime session:

const res = await fetch(`${tokenServiceUrl}/session`);
const { client_secret } = await res.json();
const ephemeralKey = client_secret.value;

The token is short-lived, so request a new one each time a session starts.

With the OSC CLI:

osc secret create eyevinn-ephtoken-svc openaikey --value "<your-openai-api-key>"
osc create eyevinn-ephtoken-svc mytokens -o OpenAiApiKey="{{secrets.openaikey}}"

Limitations

  • The /session endpoint has no authentication of its own. Anyone who can reach the instance URL can request tokens billed to your OpenAI account, so restrict access if the URL is not meant to be public.
  • Sessions are created with the model gpt-4o-realtime-preview-2024-12-17 and the voice verse.

Resources

⚠️ **GitHub.com Fallback** ⚠️