Dictation Web Component - Authentication

Access tokens and automatic token refresh for the Dictation Web Component

The Dictation Web Component requires authentication to connect to the Corti Dictation API. You provide an access token directly — the component does not handle OAuth internally.

The component is automatically hidden until authentication is provided. Once you set accessToken or authConfig, it becomes visible.

If you’re using proxying (socketUrl or socketProxy), authentication is handled by your proxy — accessToken and authConfig are ignored.

Using accessToken

Set it as an HTML attribute or JavaScript property. You must update it manually before it expires:

<corti-dictation id="dictation" accessToken="YOUR_TOKEN"></corti-dictation>

dictation.accessToken = freshToken;

This approach is suitable for short-lived sessions or prototyping. For production, use authConfig with automatic refresh.

If you’re connecting without a proxy, prefer scoped tokens so the frontend token can only access the WebSocket endpoint you need.

If you need to obtain an accessToken, you can use the Corti JavaScript SDK authentication flows and then pass the resulting token into accessToken or authConfig.

Using authConfig (recommended)

Use authConfig when you want to supply token metadata and (optionally) enable automatic refresh. If you provide a refreshAccessToken callback, the component calls it automatically when the token is about to expire:

const dictation = document.querySelector("corti-dictation");

dictation.authConfig = {
    accessToken: "<your-access-token>",
    expiresIn: 300,
    refreshToken: "<your-refresh-token>",
    refreshAccessToken: async ({ refreshToken }) => {
        const res = await fetch("/api/token/refresh");
        const data = await res.json();

        return {
            accessToken: data.access_token,
            expiresIn: data.expires_in,
            refreshToken: data.refresh_token,
        };
    },
};

Field	Type	Required	Description
accessToken	string	No	Initial access token. If omitted, the component can only obtain a token if you also provide refreshAccessToken.
expiresIn	number	No	Token lifetime in seconds. Used to schedule the next refresh.
refreshToken	string	No	Refresh token passed to refreshAccessToken when a refresh is needed (if you provide the callback).
refreshAccessToken	({ refreshToken }) => Promise	No	Optional callback for automatic refresh. Returns { accessToken, expiresIn?, refreshToken? }. Without it, you must update accessToken yourself before expiry.

How token refresh works

Under the hood, Dictation Web Component uses Corti JavaScript SDK to connect. See How token refresh works for the full behavior.

const dictation = document.querySelector("corti-dictation");

dictation.authConfig = {
    refreshAccessToken: async ({ refreshToken }) => {
        const res = await fetch("/api/token/refresh", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ refreshToken }),
        });
        const data = await res.json();

        return {
            accessToken: data.access_token,
            expiresIn: data.expires_in,
            refreshToken: data.refresh_token,
        };
    },
};

1. Initial token — If accessToken is provided in authConfig, it’s used immediately. Otherwise, refreshAccessToken is called with undefined to obtain the first token.

2. Automatic refresh — The component monitors the token’s expiration and calls refreshAccessToken before it expires. The refreshToken parameter will be:

   • undefined on the first call (if no initial refreshToken was provided)
   • The refreshToken returned from the previous refresh call

3. Seamless operation — Refresh happens in the background. Active dictation sessions continue without interruption.

Using with modular components

When using individual components, set authConfig on <dictation-root>:

<dictation-root id="root">
    <dictation-recording-button></dictation-recording-button>
</dictation-root>

<script type="module">
    import "@corti/dictation-web";

    const root = document.getElementById("root");
    root.authConfig = {
        refreshAccessToken: async ({ refreshToken }) => {
            const res = await fetch("/api/token/refresh");
            const data = await res.json();
            return {
                accessToken: data.access_token,
                expiresIn: data.expires_in,
                refreshToken: data.refresh_token,
            };
        },
    };
</script>

See also

• API Reference — full property tables for all components
• Proxy Guide — route traffic through your own server (auth handled by proxy)
• Examples — token refresh example