Get an authorization link

POST/api/v1/connected_accounts/magic_link

Creates a one-time authorization link that takes the user to the app's consent screen, or to a form for their API key, for one connection. If the user has no connected account for the connection yet, the call creates it first. When the user finishes, the account becomes ACTIVE. With user verification on, it becomes PENDING_VERIFICATION instead, and stays that way until you call Verify the user. The link expires 5 minutes after you create it, so create a new one each time you send it. The endpoint path and the connected_account.magic_link_generated event call it a magic link.

This page as markdown Authorization overview

Authorization

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

Body

connectorstring

The connection name, as shown in AgentKit > Connections.

idstring

Unique identifier for the connected account

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.

statestring

A value of your own, such as a session ID. Scalekit adds it to the request it sends to user_verify_url, so your app can check that the request is the one it started.

user_idstring

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

user_verify_urlstring

Your app's URL that Scalekit sends the user to after they approve access, to confirm they are the user your app meant. Required when the environment verifies users with a custom verifier.

scalekit_client.actions.get_authorization_link

Creates the link a user opens to connect their account.

scalekit_client.actions.get_authorization_link(
    identifier: Optional[str] = None,
    connection_name: Optional[str] = None,
    connected_account_id: Optional[str] = None,
    state: Optional[str] = None,
    user_verify_url: Optional[str] = None,
) -> MagicLinkResponse

Parameters

identifierOptional[str]

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.

connection_nameOptional[str]

The connection name, as shown in AgentKit > Connections.

connected_account_idOptional[str]

Connected account ID

stateOptional[str]

A value of your own, such as a session ID. Scalekit adds it to the request it sends to user_verify_url, so your app can check that the request is the one it started.

user_verify_urlOptional[str]

Your app's URL that Scalekit sends the user to after they approve access, to confirm they are the user your app meant. Required when the environment verifies users with a custom verifier.

Returns MagicLinkResponse: The authorization link and its expiry.

From scalekit-sdk-python 2.19.1.

scalekit.actions.getAuthorizationLink

Creates the link a user opens to connect their account.

scalekit.actions.getAuthorizationLink(
  params: {
    connectionName?: string;
    identifier?: string;
    connectedAccountId?: string;
    organizationId?: string;
    userId?: string;
    state?: string;
    userVerifyUrl?: string;
  },
): Promise<GetMagicLinkForConnectedAccountResponse>

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.

connectedAccountIdstring

Unique identifier for the connected account

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.

statestring

A value of your own, such as a session ID. Scalekit adds it to the request it sends to user_verify_url, so your app can check that the request is the one it started.

userVerifyUrlstring

Your app's URL that Scalekit sends the user to after they approve access, to confirm they are the user your app meant. Required when the environment verifies users with a custom verifier.

Returns Promise<GetMagicLinkForConnectedAccountResponse>.

From @scalekit-sdk/node 2.18.0.

Response 200

expirystring

When the link stops working: 5 minutes after you created it.

linkstring

The authorization link to send the user to. It's on your environment's domain and works once.

Errors

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

400Invalid request - missing required parameters, or a malformed connected account ID

401Authentication required - missing or invalid access token

404Not found - no connection with this name exists in the environment. Error code RESOURCE_NOT_FOUND.

Used in

Request

curl -sS -X POST \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/connected_accounts/magic_link" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connector": "gmail",
    "identifier": "user_123",
    "user_verify_url": "https://app.example.com/verify",
    "state": "[SESSION STATE]"
  }'

result = scalekit_client.actions.get_authorization_link(
    identifier="user_123",
    connection_name="gmail",
    state="[SESSION STATE]",
    user_verify_url="https://app.example.com/verify",
)

const result = await scalekit.actions.getAuthorizationLink({
  connectionName: "gmail",
  identifier: "user_123",
  state: "[SESSION STATE]",
  userVerifyUrl: "https://app.example.com/verify",
});

Response 200

{
  "link": "https://your-env.scalekit.dev/magicLink/7f0c2b9e-4d1a-4c3e-9b8f-2a6d5e1c3f40_o",
  "expiry": "2026-10-02T14:35:00Z"
}