connected-accounts.mdx

title	Manage connected accounts
description	Check status, list, delete, and update credentials for connected accounts across all connector auth types.
tags	agentauth connectedaccounts oauth2 api-key hosted-pages guide
sidebar	order label 4 Manage connected accounts
tableOfContents	maxHeadingLevel 3
prev	label link Verify user identity /agentkit/user-verification
next	label link Bring your own credentials /agentkit/advanced/bring-your-own-oauth

import { Tabs, TabItem, Aside } from '@astrojs/starlight/components';

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

Use get_or_create_connected_account as the safe default when a user may be connecting for the first time. Use get_connected_account only when you know the account already exists and you need to inspect or return its stored auth details.

```python response = actions.get_or_create_connected_account( connection_name="gmail", identifier="user_123" ) connected_account = response.connected_account print(f"Status: {connected_account.status}") ``` ```typescript const response = await actions.getOrCreateConnectedAccount({ connectionName: 'gmail', identifier: 'user_123', });

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

  </TabItem>
</Tabs>

## 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.

<Tabs syncKey="tech-stack">
  <TabItem label="Python">
```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

```typescript 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 }

  </TabItem>
</Tabs>

<Aside type="tip" title="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](/agentkit/advanced/custom-domain/).
</Aside>

## List connected accounts

<Aside type="note" title="Node.js only">
  List and delete operations are currently available in the Node.js SDK. Use the [Scalekit dashboard](https://app.scalekit.com) or REST API for Python.
</Aside>

```typescript
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 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.