Update a connected account

PUT/api/v1/connected_accounts

Updates an existing connected account, identified by its ID or by connector and identifier. Send authorization_details only when you import credentials from another platform as part of migrating to AgentKit. To change other settings, such as api_config, leave authorization_details out and the stored credentials stay as they are. To have the user connect again, use Get an authorization link instead. Returns the updated account.

This page as markdown Connected accounts overview

Authorization

Authorization: Bearer $TOKEN, an access token from the client credentials grant. See Authentication.

Body

connected_accountobjectrequired

Details of the connected account to update

Show 2 child attributes

api_configobject

JSON configuration for connector-specific API settings. Replaces the stored api_config, so send every key you want to keep. Leave it out to keep the stored configuration.

authorization_detailsobject

Credentials to import from another platform. Leave it out to keep the stored credentials.

Show 4 child attributes

google_dwdobject

Google Domain-Wide Delegation authentication — used for GOOGLE_DWD connections. Send only subject in requests; access_token, scopes, and token_expires_at are response-only.

oauth_tokenobject

OAuth 2.0 tokens your app already holds. See Import existing credentials.

static_authobject

Static credentials, such as an API key. Send them in details. The keys depend on the connection's authentication type: token for bearer, api_key for API key, and username and password for basic auth. Providers that need several API key headers take one key per header.

Show 1 child attribute

detailsobjectrequired

The credential, as a JSON object. Send the key that matches the connection's authentication type: token for bearer, api_key for API key (or, for a connector that sends several headers, one value per header, keyed by the header name), or username and password for basic auth. Add domain or version here when the provider needs them.

Show 4 child attributes

api_keystring

For an API key connection: the key. Required. Providers that need several headers take one key per header instead, named by the provider's field name or header name.

passwordstring

For a basic auth connection: the password. Leave it empty for providers that take a key as the username.

tokenstring

For a bearer connection: the access token. Required. Scalekit sends it to the provider for you.

usernamestring

For a basic auth connection: the username. Required.

trusted_idpobject

Credentials for a connection that signs in through a trusted identity provider, such as AWS Redshift. Send only db_user. Responses include access_key_id and expiry, never the secret key or session token.

connectorstring

The connection name, as shown in AgentKit > Connections.

idstring

Unique identifier for the connected account to update

identifierstring

Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address.

organization_idstring

An organization ID to key the account by instead of identifier, such as a Scalekit organization ID. Ignored when identifier is set.

user_idstring

A user ID that, with organization_id, keys the account to one user in that organization. Ignored when identifier is set.

scalekit_client.actions.update_connected_account

Update an existing connected account

scalekit_client.actions.update_connected_account(
    connection_name: str,
    identifier: str,
    authorization_details: Optional[Dict[str, Any]] = None,
    organization_id: Optional[str] = None,
    user_id: Optional[str] = None,
    connected_account_id: Optional[str] = None,
    api_config: Optional[Dict[str, Any]] = None,
) -> UpdateConnectedAccountResponse

Parameters

connection_namestrrequired

The connection name, as shown in AgentKit > Connections.

identifierstrrequired

Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address.

authorization_detailsOptional[Dict[str, Any]]

The user's credentials as a dict: {"oauth_token": {...}} for OAuth tokens (access_token, refresh_token, and optionally expires_at, when the access token expires, as a datetime in UTC, such as datetime.fromisoformat("2026-11-12T07:18:56+00:00")), or {"static_auth": {...}} for static credentials, holding the key the connection reads: token for bearer, api_key for API key (or, for a connector that sends several headers, one value per header, keyed by the header name), or username and password for basic auth. Unlike the REST body, static_auth has no details level.

organization_idOptional[str]

Organization ID

user_idOptional[str]

User ID

connected_account_idOptional[str]

Connected account ID

api_configOptional[Dict[str, Any]]

Optional API configuration for the connected account

Returns UpdateConnectedAccountResponse: The updated connected account details

From scalekit-sdk-python 2.25.0.

Also called by scalekit_client.actions.get_or_create_connected_account.

scalekit.actions.updateConnectedAccount

Update an existing connected account. Requires either connectedAccountId or both connectionName + identifier.

scalekit.actions.updateConnectedAccount(
  params: {
    connectionName?: string;
    identifier?: string;
    authorizationDetails?: MessageInitShape<typeof UpdateConnectedAccountSchema>['authorizationDetails'];
    organizationId?: string;
    userId?: string;
    connectedAccountId?: string;
    apiConfig?: UpdateConnectedAccount['apiConfig'];
  },
): Promise<UpdateConnectedAccountResponse>

Parameters

connectionNamestring

The connection name, as shown in AgentKit > Connections.

identifierstring

Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address.

authorizationDetailsMessageInitShape<typeof UpdateConnectedAccountSchema>['authorizationDetails']

The user's credentials: OAuth tokens as { case: "oauthToken", value } (set value.expiresAt to when the access token expires, in UTC, such as timestampFromDate(new Date("2026-11-12T07:18:56Z")) with timestampFromDate from @bufbuild/protobuf/wkt), or static credentials as { case: "staticAuth", value }, where value.details holds the key the connection reads: token for bearer, api_key for API key (or, for a connector that sends several headers, one value per header, keyed by the header name), or username and password for basic auth.

organizationIdstring

An organization ID to key the account by instead of identifier, such as a Scalekit organization ID. Ignored when identifier is set.

userIdstring

A user ID that, with organization_id, keys the account to one user in that organization. Ignored when identifier is set.

connectedAccountIdstring

Unique identifier for the connected account to update

apiConfigUpdateConnectedAccount['apiConfig']

JSON configuration for connector-specific API settings. Replaces the stored api_config, so send every key you want to keep. Leave it out to keep the stored configuration.

Returns Promise<UpdateConnectedAccountResponse>.

From @scalekit-sdk/node 2.22.0.

Also called by scalekit.actions.getOrCreateConnectedAccount.

Response 200

connected_accountobject

The updated connected account with refreshed credentials, new token expiry, and modified configuration settings.

Show 13 child attributes

api_configobject

Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags.

authorization_detailsobject

The account's credentials. Set the one that matches the connection's auth type - oauth_token, static_auth, google_dwd or trusted_idp.

Show 4 child attributes

google_dwdobject

Google Domain-Wide Delegation authentication — used for GOOGLE_DWD connections. Send only subject in requests; access_token, scopes, and token_expires_at are response-only.

oauth_tokenobject

OAuth 2.0 tokens your app already holds. See Import existing credentials.

static_authobject

trusted_idpobject

authorization_typestring (enum)

Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods.

OAUTHAPI_KEYBASIC_AUTHBEARER_TOKENCUSTOMBASICOAUTH_M2MTRELLO_OAUTH1GOOGLE_DWDTRUSTED_IDPSMART_FHIRNO_AUTH

connection_idstring

Reference to the parent connection configuration. Links this account to a specific connector setup in your environment.

connectorstring

The connection name, as shown in AgentKit > Connections.

idstring

Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca_'.

identifierstring

Your app's ID for the user, the value passed when the account was created.

is_org_wide_credentialboolean

Whether this is the shared credential of an org-wide connection, which every user's tool calls on that connection use. false for a user's own account.

last_used_atstring

Timestamp when this connected account was last used to make an API call. Useful for tracking active connections.

providerstring

The app the account connects to, such as GMAIL or SLACK.

statusstring (enum)

Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification.

ACTIVEEXPIREDPENDING_AUTHPENDING_VERIFICATIONDISCONNECTED

token_expires_atstring

Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized.

updated_atstring

Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes.

Errors

Every error has the same body: code, message and details. See Errors and rate limits.

400Invalid request - missing required fields, invalid authorization details, or validation failed

401Authentication required - missing or invalid access token

404Connected account not found - the specified account does not exist

Request

1
curl -sS -X PUT \
2
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/connected_accounts" \
3
  -H "Authorization: Bearer $TOKEN" \
4
  -H "Content-Type: application/json" \
5
  -d '{
6
    "connector": "gmail",
7
    "identifier": "user_123",
8
    "connected_account": {
9
      "authorization_details": {
10
        "oauth_token": {
11
          "access_token": "[NEW ACCESS TOKEN]",
12
          "refresh_token": "[NEW REFRESH TOKEN]",
13
          "scopes": [
14
            "https://www.googleapis.com/auth/gmail.readonly"
15
          ]
16
        }
17
      }
18
    }
19
  }'

result = scalekit_client.actions.update_connected_account(
    connection_name="gmail",
    identifier="user_123",
    authorization_details={
        "oauth_token": {
            "access_token": "[NEW ACCESS TOKEN]",
            "refresh_token": "[NEW REFRESH TOKEN]",
            "scopes": ["https://www.googleapis.com/auth/gmail.readonly"],
        },
    },
)

const result = await scalekit.actions.updateConnectedAccount({
  connectionName: "gmail",
  identifier: "user_123",
  authorizationDetails: {
    details: {
      case: "oauthToken",
      value: {
        accessToken: "[NEW ACCESS TOKEN]",
        refreshToken: "[NEW REFRESH TOKEN]",
        scopes: ["https://www.googleapis.com/auth/gmail.readonly"],
      },
    },
  },
});

Request with a new API key

1
curl -sS -X PUT \
2
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/connected_accounts" \
3
  -H "Authorization: Bearer $TOKEN" \
4
  -H "Content-Type: application/json" \
5
  -d '{
6
    "connector": "api-key-connection",
7
    "identifier": "user_123",
8
    "connected_account": {
9
      "authorization_details": {
10
        "static_auth": {
11
          "details": {
12
            "api_key": "[NEW API KEY]"
13
          }
14
        }
15
      }
16
    }
17
  }'

result = scalekit_client.actions.update_connected_account(
    connection_name="api-key-connection",
    identifier="user_123",
    authorization_details={
        "static_auth": {
            "api_key": "[NEW API KEY]",
        },
    },
)

const result = await scalekit.actions.updateConnectedAccount({
  connectionName: "api-key-connection",
  identifier: "user_123",
  authorizationDetails: {
    details: {
      case: "staticAuth",
      value: {
        details: {
          api_key: "[NEW API KEY]",
        },
      },
    },
  },
});

Response 200

1
{
2
  "connected_account": {
3
    "id": "ca_24834495392086178",
4
    "connection_id": "conn_70219645518265104",
5
    "connector": "gmail",
6
    "identifier": "user_123",
7
    "provider": "GMAIL",
8
    "authorization_type": "OAUTH",
9
    "status": "ACTIVE",
10
    "is_org_wide_credential": false,
11
    "token_expires_at": "2026-10-02T15:30:00Z",
12
    "last_used_at": "2026-10-02T14:31:07Z",
13
    "updated_at": "2026-10-02T14:30:00Z",
14
    "authorization_details": {
15
      "oauth_token": {
16
        "access_token": "[NEW ACCESS TOKEN]",
17
        "refresh_token": "[NEW REFRESH TOKEN]",
18
        "scopes": [
19
          "https://www.googleapis.com/auth/gmail.readonly"
20
        ]
21
      }
22
    }
23
  }
24
}