Connections are a way to authenticate Attio users to external services. You simply setup a connection configuration in the Developer Portal and App SDK will handle that your users are authenticated to the external service. You will be able to retrieve the connection value whether it’s a secret or an access token in your server functions.

​
Example: Authenticating to an external mail sequencing API

To get started, head to the Developer Portal and open the Connections tab for your app. Enable either a User or Workspace connection:
  • User connections authenticate with external services on behalf of individual users. Use this if you want to track who performed an action, for example, who added a prospect to a sequence.
  • Workspace connections authenticate on behalf of the entire workspace. These are easier for Attio users to set up, since only one person in the workspace needs to authenticate with the external service. However, if you want to track who performed an action, you’ll need to enable a user connection.
It’s possible to enable both connection types, though most apps only require one.
Once you have enabled a connection, you can retrieve the connection value in your server functions. We can modify the example from Making HTTP requests to use a connection to authenticate to the external mail sequencing API, instead of using a hardcoded API key.
add-to-sequence.server.ts
// You will need to call the correct function
// based on the connection type you've enabled
import {getUserConnection, getWorkspaceConnection} from "attio/server"

export default async function addToSequence({
    email,
    sequenceId,
    mailboxId,
}: {
    email: string
    sequenceId: number
    mailboxId: number
}): Promise<Record<string, string>> {
    const response = await fetch(`https://emailsequencingtool.com/api/v1/sequences`, {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            // ℹ️ Here we are using User connection instead of hardcoded API key
            "Authorization": `Bearer ${getUserConnection().value}`,
        },
        body: JSON.stringify({email, sequenceId, mailboxId}),
    })

    if (!response.ok) {
        throw new Error(`Failed to add prospect to sequence: ${await response.text()}`)
    }

    // ℹ️ better to parse with a tool like Zod than to cast
    const body: {data: Record<string, string>} = await response.json()

    return body.data
}
When a user is not authenticated with the external service, calling getUserConnection/getWorkspaceConnection will throw an error. The App SDK handles this for you by catching the error and showing a prompt that asks the user to connect their account.