Sovos.com Contact Support

Get Started with Trust

Sovos Account

Operator session

Associate an operator's verified identity with user verifications the operator performs.

By enabling the operator session feature, you ensure that each verification records this association in the audit log.

This feature is enabled through an optional parameter. If you don't send the parameter, the verification continues normally without associating an operator. However, if you send the parameter and it is invalid or expired, the verification is rejected.

How operator session works

An operator session starts with a standard identity verification. When the id_token or the refresh_token are sent as the operator_id_token parameter in a client verification, the system knows to associate that verification with the operator. The flow works as follows:

  1. The operator performs an identity verification, the same as any other verification in the system. The resulting id_token identifies the operator for the duration of the session.

  2. If the offline_access scope is requested, the integration also receives a refresh_token, which can be used to renew the id_token without requiring the operator to verify again.

  3. When the operator starts a verification, the integration adds the operator's id_token as the operator_id_token query parameter in the authorization URL. This is what tells the system that the verification corresponds to an operator session.

  4. The system validates the token automatically. If valid, the operator is associated with the audit log. If invalid or expired, the verification is rejected.

Note:

This parameter is optional. If the parameter is absent, the verification proceeds normally without an operator association. For more details on using this feature, see Implement operator session.

operator_id_token parameter

Parameter Value
operator_id_token A JWT id_token or refresh_token from the operator login.

Add the operator_id_token as a query parameter in the authorization URL when starting a verification.

Behavior by scenario

Scenario Result
Token valid and active The operator is associated with the audit log.
Token expired Verification is rejected and the operator must log in again.
Token with invalid signature Verification is rejected because the token is not valid.
Parameter absent Verification continues normally without an operator association.
Important:

If you send the operator_id_token parameter but the token is invalid or expired, the verification is rejected. Only authenticated operators can perform verifications.

Available endpoints

Environment Authorization URL
UAT https://accounts-uat.trust.sovos.com/oauth2/auth
Production https://accounts.trust.sovos.com/oauth2/auth

Implement operator session

Example on how to implement the operator session feature to link an operator's verified identity to the verifications they perform.

Confirm:

  • The operator has completed a successful login through the verification flow.

  • Sovos has enabled the offline_access scope on your client credentials. Contact your Sovos representative to request this.

  • The operator and the verification use the same OAuth2 client_id. See Token management.

The operator session feature associates an operator's identity with the identity verifications the operator performs on other people (users). The operator_id_token parameter is optional. If you don't send it, the verification continues normally without associating an operator. If it is invalid or expired, the verification is rejected.

The operator session can remain active for an extended period using the refresh_token. When the operator's id_token expires, you can use the refresh_token to obtain a new id_token and continue sending it in the operator_id_token parameter without requiring the operator to log in again, as explain in step 4.

See Operator session reference.

  1. Log the operator in and save both tokens.

    Perform the operator login, requesting the offline_access scope to receive both an id_token and a refresh_token. Save both tokens for use during user verifications.

    JAVASCRIPT 
    // After the operator completes their login
const tokensOperador = await completarLogin(codigoAutorizacion);

// Save the id_token for later use
sessionStorage.setItem('operator_id_token', tokensOperador.id_token);

// Login with offline_access to obtain a refresh_token
const paramsLogin = new URLSearchParams({
  response_type: 'code',
  client_id: clientId,
  scope: 'openid offline offline_access profile',
  redirect_uri: redirectUri,
  code_challenge: generarCodeChallenge(),
  code_challenge_method: 'S256',
  acr_values: acrOperador,
});

// After login, save both tokens
sessionStorage.setItem('operator_id_token', tokens.id_token);
sessionStorage.setItem('operator_refresh_token', tokens.refresh_token);
  2. Check whether the operator's id_token is still valid before each verification.

    Decode the id_token and check the exp claim. The operator token has the same duration as the standard OAuth2 id_token.

    JAVASCRIPT 
    function tokenOperadorVigente(): boolean {
  const token = sessionStorage.getItem('operator_id_token');
  if (!token) return false;
  try {
    const payload = JSON.parse(atob(token.split('.')[1]));
    return (payload.exp * 1000) > Date.now();
  } catch {
    return false;
  }
}

    • If the token is valid, continue to step 3.

    • If the token has expired, continue to step 4.

  3. Add operator_id_token as a query parameter in the authorization URL.

    Include the operator's id_token as the operator_id_token query parameter when constructing the authorization URL for the verification.

    JAVASCRIPT 
    function construirURLVerificacion(clientId: string, redirectUri: string, acr: string): string {
  const params = new URLSearchParams({
    response_type: 'code',
    client_id: clientId,
    scope: 'openid',
    redirect_uri: redirectUri,
    code_challenge: generarCodeChallenge(),
    code_challenge_method: 'S256',
    acr_values: acr,
  });

  // Add the operator context if available
  const tokenOperador = sessionStorage.getItem('operator_id_token');
  if (tokenOperador) {
    params.set('operator_id_token', tokenOperador);
  }

  return `${AUTHORIZATION_ENDPOINT}?${params.toString()}`;
}
    Important:

    If you send the operator_id_token parameter but the token is invalid or expired, the verification is rejected. Only authenticated operators can perform verifications.

  4. Renew the id_token using the refresh_token if the token has expired.

    Use the refresh_token to obtain a new id_token without requiring the operator to log in again. This extends the operator's session while the refresh_token remains valid.

    JAVASCRIPT 
    async function renovarTokenOperador(): Promise<string | null> {
  const refreshToken = sessionStorage.getItem('operator_refresh_token');
  if (!refreshToken) return null;

  const response = await fetch(`${TOKEN_ENDPOINT}`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${btoa(`${clientId}:${clientSecret}`)}`,
    },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      refresh_token: refreshToken,
    }),
  });

  if (!response.ok) return null;

  const data = await response.json();
  sessionStorage.setItem('operator_id_token', data.id_token);
  sessionStorage.setItem('operator_refresh_token', data.refresh_token);
  return data.id_token;
}

// Before starting a verification
async function obtenerTokenOperadorValido(): Promise<string | null> {
  if (tokenOperadorVigente()) {
    return sessionStorage.getItem('operator_id_token');
  }

  // Attempt to renew with the refresh_token
  const nuevoToken = await renovarTokenOperador();
  if (nuevoToken) {
    return nuevoToken;
  }

  // Renewal failed — the operator must log in again
  sessionStorage.removeItem('operator_id_token');
  sessionStorage.removeItem('operator_refresh_token');
  return null;
}

    If renewal fails, the operator must log in again before verifications can continue.

  5. Handle verification rejection due to an invalid operator token in the callback.

    When the backend rejects the verification due to an invalid operator token, the OAuth2 provider returns an error in the callback with a reference to operator_id_token. The client must detect the error, clear the stored token, close the operator session, and redirect the operator to the login page.

    JAVASCRIPT 
    // In the verification callback
const errorParam = new URLSearchParams(window.location.search).get('error');
const errorDescription = new URLSearchParams(window.location.search).get('error_description');

// Detect whether the error is due to an invalid operator token
const esErrorOperador = `${errorParam} ${errorDescription || ''}`
  .toLowerCase()
  .includes('operator_id_token');

if (esErrorOperador) {
  // Clear the token and redirect to the operator login
  sessionStorage.removeItem('operator_id_token');
  cerrarSesionOperador();
  redirigirALogin();
}

When the operator token is valid, the operator is associated with the audit log entry for each verification performed during the session. The operator's name is displayed on the verification screen.

Review the behavior reference to understand how the system responds in each scenario.

Last updated: October 14, 2026