> **Building with AI coding agents?** If you're using an AI coding agent, install the official Scalekit plugin. It gives your agent full awareness of the Scalekit API — reducing hallucinations and enabling faster, more accurate code generation.
>
> - **Claude Code**: `/plugin marketplace add scalekit-inc/claude-code-authstack` then `/plugin install <auth-type>@scalekit-auth-stack`
> - **GitHub Copilot CLI**: `copilot plugin marketplace add scalekit-inc/github-copilot-authstack` then `copilot plugin install <auth-type>@scalekit-auth-stack`
> - **Codex**: run the bash installer, restart, then open Plugin Directory and enable `<auth-type>`
> - **Skills CLI** (Windsurf, Cline, 40+ agents): `npx skills add scalekit-inc/skills --list` then `--skill <skill-name>`
>
> `<auth-type>` / `<skill-name>`: `agentkit`, `full-stack-auth`, `mcp-auth`, `modular-sso`, `modular-scim` — [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# 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}")
```
  ```typescript
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
```
  ```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
}
```
**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/).

## List connected accounts
**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.

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

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

---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |