Manage connected accounts

A connected account is the per-user record that holds a user’s credentials and tracks their authorization state for a specific connection. Scalekit creates one automatically when a user completes authentication.

Account states

State	Meaning
PENDING	User hasn’t completed authentication
ACTIVE	Credentials valid, ready for tool calls
EXPIRED	Credentials expired or invalidated, re-authentication required
REVOKED	User revoked access or credentials were invalidated
ERROR	Authentication or configuration error

Check account status

Python

response = actions.get_connected_account(
    connection_name="gmail",
    identifier="user_123"
)
connected_account = response.connected_account
print(f"Status: {connected_account.status}")

Node.js

const response = await actions.getConnectedAccount({
  connectionName: 'gmail',
  identifier: 'user_123',
});

console.log('Status:', response.connectedAccount?.status);

Handle inactive accounts

When a connected account isn’t ACTIVE, generate a new authorization link and send it to the user.

The link opens a Hosted Page, a Scalekit-hosted UI that adapts automatically based on the connection’s auth type:

• OAuth connectors: presents the provider’s OAuth consent screen
• API key, basic auth, or other connectors: presents a form to collect the required credentials

Your code is the same regardless of connector type. Scalekit determines the right flow based on the connection configuration.

Python

if connected_account.status != "ACTIVE":
    link_response = actions.get_authorization_link(
        connection_name="gmail",
        identifier="user_123"
    )
    # Redirect or send link_response.link to the user

Node.js

import { ConnectorStatus } from '@scalekit-sdk/node/lib/pkg/grpc/scalekit/v1/connected_accounts/connected_accounts_pb';

if (connectedAccount?.status !== ConnectorStatus.ACTIVE) {
  const linkResponse = await actions.getAuthorizationLink({
    connectionName: 'gmail',
    identifier: 'user_123',
  });
  // Redirect or send linkResponse.link to the user
}

Customize hosted pages

By default, hosted pages use Scalekit’s branding. You can configure your own logo, colors, and custom domain so the pages look like part of your product. See Custom domain.

List connected accounts

Node.js only

List and delete operations are currently available in the Node.js SDK. Use the Scalekit dashboard or REST API for Python.

const listResponse = await actions.listConnectedAccounts({
  connectionName: 'gmail',
});
console.log('Connected accounts:', listResponse);

Delete a connected account

Deleting a connected account removes the user’s credentials and authorization state. The user must re-authenticate to reconnect.

await actions.deleteConnectedAccount({
  connectionName: 'gmail',
  identifier: 'user_123',
});

Update OAuth scopes

Scopes apply to OAuth connectors only. For non-OAuth connectors (API key, basic auth, and similar), generate a new authorization link and the hosted page will collect updated credentials.

To request additional OAuth scopes from an existing connected account:

1. Update the connection’s scopes in Agent Auth > Connections > Edit.
2. Generate a new authorization link for the user.
3. The user completes the OAuth consent screen, approving the updated scopes.
4. Scalekit updates the connected account with the new token set.