Authentication

Every call sends one credential in the Authorization header:

Authorization: Bearer <credential>

There are two credentials, for two different callers. An operation takes exactly one of them: the API reference names it on each operation.

Credential	Held by	Accepted by
Project secret	Your backend	End-user management: /v1/users and /v1/users/{user_id}/tokens
User token	Your app, for one end user	Everything an end user does: sessions, messages, events, files, generations, voice, transcription, /v1/me

A user token sent to a management operation is refused with 403 permission_denied. A project secret sent to an end-user operation is refused with 401 invalid_token, like any credential that is not a valid user token.

Project secrets

A project secret identifies your project. You create one in the console when you create the project, and more on the project's Keys page. The console shows a secret's full value only once, when it is created; afterwards it shows only its first characters, so you can tell secrets apart.

• Keep secrets on your servers. Anyone holding one can create, disable and delete your end users and issue them tokens.
• Use one secret per service or environment, so you can revoke one without touching the rest.
• To rotate a secret: create a new one, deploy it, then revoke the old one. A revoked secret is refused from then on with 401 invalid_secret.

While a project is disabled, its secrets are refused with 403 project_disabled and its users' tokens with 401 project_disabled.

User tokens

A user token lets one end user's app call the API as that user. Your backend issues it:

curl -s "$NEWEYES_API_BASE/v1/users/$USER_ID/tokens" -X POST \
  -H "Authorization: Bearer $NEWEYES_PROJECT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"expires_in": 3600}'

A user's first token can also come with the user: create it with issue_token: true (and expires_in, if you want another lifetime) and the answer carries the token as token.

• Lifetime. expires_in is in seconds, from 60 to 86,400 (24 hours); one hour when you leave it out. No token lives longer than 24 hours, so a token copied out of an app stops working by itself.
• Refresh. Issue a new token before the old one expires — when your app starts, or when a call answers 401 token_expired. Issuing a new token leaves the earlier ones working.
• Revoke. DELETE /v1/users/{user_id}/tokens revokes every token issued to that user so far, for example when one may have leaked; each is refused from then on with 401 invalid_token. Tokens issued afterwards work. The console's Revoke all tokens does the same for every user of a project at once.
• Disable. A disabled user's tokens stop working (401 user_disabled), and no new one can be issued until you enable the user again.

GET /v1/me returns the end user a token belongs to, with their project — a cheap way for your app to check that its token still works.

Voice connections

A voice call does not send the user token over its WebSocket. POST /v1/realtime/sessions (with the user token) returns a short-lived client_secret that opens one connection; see Realtime voice.

The console

The console uses your Google account, not a secret. It is where you create projects, manage their secrets and end users, and read usage, transactions, calls and the audit log. See the console guide.