V- Modal AI: Visual Video / Image Search - Flutter Video SDK
Manage runtime credentials and app-user sessions
Choose the credential pattern first in authentication.md.
This guide's tenant coordinator applies to direct API-key authentication.
For server-enforced user grants, use VModal.connectWithBackend and the scoped
coordinator described in auth_user_backend_mode.md.
Do not share a scoped credential source across users or attach it to the
tenant-wide rotation flow.
Retrieve credentials through the host's authenticated, trusted service and
keep them in memory. Direct VModal API keys identify the tenant principal; Firebase,
Clerk, or another host identity system supplies the stable app-user ID. A and B
may share one tenant key and auth.me() response. That response never selects
their local owner namespace or proves their content permissions. Scoped auth/me
instead adds the verified app subject/project/policy/grants and is checked
against the envelope before the backend connection becomes ready.
Backend connection lifecycle
final backend = await VModal.connectWithBackend(
expectedAppUserId: signedInUser.id,
expectedProjectId: 'framebase',
loadToken: () async => ScopedTokenEnvelope.fromJson(
await developerApi.createVmodalSession(),
),
);
final library = backend.scope('my_library');
await backend.refresh(); // coalesced renewal, no mutation replay
await backend.close(); // local VModal cleanup; host owns sign-out
The callback verifies current host login through the developer backend on every acquisition and returns only a short-lived VModal-signed token. Parse/identity errors differ from temporary availability failures; see the backend guide and the reference adapter.
Shared HTTP gateway paths check readiness before taking Bearer snapshots.
Proactive renewal leeway is capped at half the lifetime. Expiry uses
expires_at, and renewal is coalesced. A valid token may continue during a
temporary outage; expired or rejected revisions block dispatch. Same-policy
renewal preserves session and owner; changed policy/binding requires reconnect.
Observe token-free ready, refreshing, unavailable, expired, invalidated
and closed events at the account owner. Call close() at the start of an
account transition and discard retired scopes/UI. Backend owner identity
includes project/service/tenant/user and excludes bearer, expiry and jti.
The tenant-specific sections below retain their contract. The tenant option
retainOnRenewalFailure is not a backend-mode fallback to broader credentials.
Session-bound configuration
final config = SdkConfig(); // gateway mode
final namespace = SessionContext.serviceNamespaceFor(config);
final credentials = TenantCredentialSource(
serviceNamespace: namespace,
tenantId: tenantId,
expectedPrincipal: tenantPrincipal,
initialKey: runtimeTenantKey,
renew: () async => TenantCredential(
serviceNamespace: namespace,
tenantId: tenantId,
principal: tenantPrincipal,
apiKey: await trustedIssuer.currentTenantKey(),
),
);
final manager = UserSessionManager(
config: config,
credentialSource: credentials,
);
The host's issuer/resolver must authenticate and validate the credential's
service/tenant/principal binding. These fields are compared locally; self-reported
labels on an arbitrary key are not proof. session.verifyPrincipal(...) can
add an auth.me() tenant-principal check. It does not identify the app user or
validate that user's mapping. Prefer authoritative integer issuerVersion
values when the issuer supports them; when absent, the trusted resolver must
return its currently valid key. auth.me() cannot order opaque keys by age.
Coordinate tenant rotation
credentials.renewCredential() shares one normal renewal Future across active
matching providers. install(TenantCredential(...)) installs a trusted external
replacement. renewCredential(supersede: true) deliberately fences earlier
renewal tickets. Accepted revision and request ticket checks reject late results;
authoritative issuer versions reject rollback. Commit is atomic within the
isolate, updates only live matching providers, and new sessions attach/read the
latest revision without an asynchronous gap. Closing A unsubscribes its provider
without canceling shared renewal needed by B.
credentials.install(TenantCredential(
serviceNamespace: namespace,
tenantId: tenantId,
principal: tenantPrincipal,
apiKey: replacementTenantKey,
));
A credential-only replacement preserves sessionId, stable owner/scope keys,
app user, mapping, policy, and multipart checkpoint namespace. Tenant, endpoint,
or principal changes are rejected in place: build a correctly bound source and
fresh sessions. Grant/mapping changes also require invalidation and fresh policy
resolution, even when the key or app-user ID stays equal.
By default renewal failure blocks tenant calls, retains no fallback authority,
and returns a classified TenantAuthException. It does not log out the host
app user or change the active owner. retainOnRenewalFailure: true is available
only when the host's authoritative validity policy permits using the prior key.
revoke() is an authoritative current-credential revocation and blocks gateway
calls; a stale request's 401 cannot revoke a newer accepted revision. Recover
the tenant connection through the trusted source rather than falling back to a
broader credential. credentials.close() retires the shared coordinator;
closing one user session leaves the coordinator available to another.
Request snapshots and recovery
The HTTP layer captures a binding/revision and header snapshot at request construction. Ordinary retries retain that snapshot. Rotation does not rewrite an existing request. New requests read the latest committed credential. Existing calls can finish with the prior key while the service still accepts it; every attempt and delivery remains guarded by its original app-user lease.
An eligible active GET/HEAD read can recover from 401 at most once per logical
request by consulting the coordinator and reconstructing fresh headers. It
shares a bounded attempt budget with ordinary retries. A second denial returns
a tenant-auth error while preserving app-user identity. 403 is never a general
refresh trigger. Uploads, index submissions, deletions, and other mutations are
never automatically replayed through auth recovery; ambiguous completion remains
unknown and requires deliberate reconciliation. Multipart continuation uses only
its existing explicit status/part/resume protocol and validated owner checkpoints.
Signed URLs have independent validity and expiry. Rotating or revoking the tenant key does not promise to revoke an already issued storage/media capability. Never attach a replacement bearer to a signed storage request. The session guard still blocks later local signed-upload dispatch and media delivery after logout.
Account changes and the host boundary
Call manager.logout() or manager.openResolvedSession(...) at the start of
an identity transition. Invalidation happens before asynchronous resolution or
cleanup. Clear old displayed images, playback, navigation/restoration, and
histories; check the current view generation before applying asynchronous host
state updates. Persisted owner data may remain for a later verified activation,
but old runtime handles never become valid again. Local cache reuse requires
current policy validation.
The compatible tenant-scoped API still accepts MutableApiKeyProvider:
final provider = MutableApiKeyProvider(runtimeTenantKey);
final project = VModal.configure(
projectId: 'food_app',
apiKeyProvider: provider,
);
provider.rotate(replacementTenantKey); // later requests only
provider.close(); // permanently disables reads and rotation
await project.close();
VmodalClient/VModalProject bypass user-session isolation; the host must own
their complete cancellation, cache/checkpoint partitioning, and account-switch
contract. Never use projectId or tenant identity as proof of app-user identity.
Never commit keys, put them in assets, log them, persist them in jobs/archives,
or treat compile-time --dart-define values as production credential storage.
See the SDK contract for result provenance, restricted media, local storage fencing, and the shared-key modified-client limitation.