Installations

Some providers separate app-level credentials from user-level credentials. A Slack bot installed in a workspace has its own token. Individual users within that workspace may also have personal OAuth grants. Authpipe models this with installations (app-level) and connections (user-level).

When to use installations

Use installations when the provider has an app/bot model:

Provider	Installation	User Connection
Slack	Bot token for the workspace	Individual user’s OAuth token
GitHub App	App installation token for the org	User’s personal access token
Microsoft Teams	App registration in a tenant	User’s delegated token

Providers that don’t have an installation model (e.g., Google Drive, Dropbox) use connections directly.

Create an install session

Node

const session = await authpipe.createInstallSession({
  provider: "slack",
  tenantId: "org_acme",
  userId: "user_admin",
  redirectUrl: "https://yourapp.com/integrations/installed",
  permissions: ["channels:read", "chat:write"],
});

// Redirect admin to session.authorization_url
res.redirect(session.authorization_url);

Go

session, err := client.CreateInstallSession(ctx, &authpipe.CreateInstallSessionParams{
  Provider:    "slack",
  TenantID:    "org_acme",
  UserID:      "user_admin",
  RedirectURL: "https://yourapp.com/integrations/installed",
  Permissions: []string{"channels:read", "chat:write"},
})

Python

session = client.create_install_session(
    provider="slack",
    tenant_id="org_acme",
    user_id="user_admin",
    redirect_url="https://yourapp.com/integrations/installed",
    permissions=["channels:read", "chat:write"],
)

After the admin completes the installation flow, Authpipe stores the installation with a bot/app token.

Two-tier credential retrieval

With both an installation and user connections, getCredential resolves across both tiers.

Default: try connection, fall back to installation

const result = await authpipe.getCredential({
  provider: "slack",
  tenantId: "org_acme",
  userId: "user_jane",
});
// If user_jane has a connection → returns her token (source: "connection")
// If not → returns the bot token (source: "installation")

Installation only

const result = await authpipe.getCredential({
  provider: "slack",
  tenantId: "org_acme",
  credentialFor: "installation",
});
// Always returns the bot token, ignoring connections

User only (no fallback)

const result = await authpipe.getCredential({
  provider: "slack",
  tenantId: "org_acme",
  userId: "user_jane",
  credentialFor: "user",
});
// Returns user_jane's token, or fails if she hasn't connected

Managing installations

Search installations

Node

const installations = await authpipe.searchInstallations({
  filter: { tenant_id: { eq: "org_acme" } },
});

Go

resp, err := client.SearchInstallations(ctx, &authpipe.SearchRequest{
  Filter: map[string]map[string]interface{}{
    "tenant_id": {"eq": "org_acme"},
  },
})

Python

from authpipe.types import SearchRequest

resp = client.search_installations(SearchRequest(
    filter={"tenant_id": {"eq": "org_acme"}},
))

Get an installation

Node

const installation = await authpipe.getInstallation("inst_abc123");

Go

inst, err := client.GetInstallation(ctx, "inst_abc123")

Python

inst = client.get_installation(installation_id="inst_abc123")

Delete an installation

Deleting an installation sets its status to deleted and revokes all child connections.

Node

await authpipe.deleteInstallation("inst_abc123");

Go

err := client.DeleteInstallation(ctx, "inst_abc123")

Python

client.delete_installation(installation_id="inst_abc123")

Reinstallation

If the same app is reinstalled in the same external workspace, Authpipe upserts the existing installation (updates tokens and permissions) instead of creating a duplicate. The provider_installation_id is the deduplication key.