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. Your code creates it, with get_or_create_connected_account or when it requests an authorization link for the user. The user activates it by authorizing.

See Troubleshoot connection and OAuth errors for what to do in each state.

Use get_or_create_connected_account as the safe default when a user may be connecting for the first time. When the account already exists and you only need its status, use get_connected_account_details in Python, which returns the account without its credentials. In Node.js, use getConnectedAccount.

response = actions.get_or_create_connected_account(
    connection_name="github-connect",
    identifier="user_123"
)
connected_account = response.connected_account
print(f"Status: {connected_account.status}")

const response = await actions.getOrCreateConnectedAccount({
  connectionName: 'github-connect',
  identifier: 'user_123',
});
const connectedAccount = response.connectedAccount;
console.log('Status:', connectedAccount?.status);

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

The link opens the Hosted Connect Widget, a Scalekit-hosted page that adapts to 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.

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

import { ConnectorStatus } from '@scalekit-sdk/node';

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

A connected account can leave the ACTIVE state on its own, with no action from you or the user. When that happens, the next tool call fails until the user authorizes again. To catch it early, listen for the connected_account.status_updated webhook instead of waiting for a failed call.

OAuth connected accounts most often move to EXPIRED because:

• The provider revoked the refresh token. A password change, an admin-initiated token revocation, or a provider security policy invalidates the refresh token, so Scalekit can no longer obtain new access tokens.
• The refresh token expired. Providers cap refresh-token lifetimes (for example, 30 or 180 days), and the expiry is rarely surfaced in advance.
• No refresh token was issued. When the connection’s scopes don’t request offline access, the provider returns only a short-lived access token and no refresh token to renew it.
• The provider hit a per-user token limit. Some providers keep only a fixed number of refresh tokens per user and app, and silently drop the oldest ones when a user reconnects repeatedly.

In every case, the user authorizes again. When no refresh token was issued, first add the provider’s offline-access scope to the connection, or the account expires again soon after. Offline scopes don’t raise a provider’s per-user token limit: to stay under it, send a new authorization link only when the account isn’t ACTIVE.

Scalekit sends a connected_account.status_updated webhook when an account’s status changes, with the old and new status. When status becomes EXPIRED or DISCONNECTED, create a new authorization link and ask the user to reconnect. Listen for account events shows how to add an endpoint, verify the signature, and handle each event.

list_response = actions.list_connected_accounts(
    connection_name="github-connect",
)
for account in list_response.connected_accounts:
    print(account.identifier, account.status)

import { ConnectorStatus } from '@scalekit-sdk/node';

const listResponse = await actions.listConnectedAccounts({
  connectionName: 'github-connect',
});
for (const account of listResponse.connectedAccounts) {
  console.log(account.id, account.identifier, ConnectorStatus[account.status]);
}

Deleting a connected account removes the user’s credentials and authorization state. The user must authorize again to reconnect.

actions.delete_connected_account(
    connection_name="github-connect",
    identifier="user_123",
)

await actions.deleteConnectedAccount({
  connectionName: 'github-connect',
  identifier: 'user_123',
});

Scopes apply to OAuth connectors only. For non-OAuth connectors (API key, basic auth, and similar), generate a new authorization link and the Hosted Connect Widget collects the new credentials.

To request additional OAuth scopes from an existing connected account:

1. Update the connection’s scopes in AgentKit > 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.