OAuth Connections

OAuth connections are the primary way to get credentials for third-party APIs. Authpipe handles the full OAuth 2.0 flow: authorization URL generation with PKCE, callback handling, token exchange, encrypted storage, and automatic refresh.

Flow overview

1. Your backend creates an auth session via the SDK.
2. You redirect the user to the authorization_url.
3. The user authorizes with the provider (e.g., Google, Slack).
4. The provider redirects to Authpipe’s callback URL.
5. Authpipe exchanges the code for tokens, encrypts and stores them.
6. Authpipe redirects the user to your redirect_url.
7. Your backend calls getCredential to retrieve a valid token.

Configure a provider

Before users can connect, register your OAuth app credentials.

Node

const config = await authpipe.createProviderConfig({
  provider_id: "slack",
  client_id: "your-slack-client-id",
  client_secret: "your-slack-client-secret",
  oauth_redirect_url: "https://api.authpipe.dev/oauth/callback",
  attachment: "user", // or "tenant"
  enabled: true,
  scopes: ["channels:read", "chat:write"],
});

Go

config, err := client.CreateProviderConfig(ctx, &authpipe.CreateProviderConfigParams{
  ProviderID:       "slack",
  ClientID:         "your-slack-client-id",
  ClientSecret:     "your-slack-client-secret",
  OAuthRedirectURL: "https://api.authpipe.dev/oauth/callback",
  Attachment:       "user",
  Enabled:          true,
  Scopes:           []string{"channels:read", "chat:write"},
})

Python

config = client.create_provider_config(
    provider_id="slack",
    client_id="your-slack-client-id",
    client_secret="your-slack-client-secret",
    oauth_redirect_url="https://api.authpipe.dev/oauth/callback",
    attachment="user",
    enabled=True,
    scopes=["channels:read", "chat:write"],
)

The oauth_redirect_url must be https://api.authpipe.dev/oauth/callback (or your self-hosted equivalent) and must match what you registered in the provider’s developer console.

Create an auth session

When a user initiates a connection, create an auth session and redirect them.

Node

const session = await authpipe.createAuthSession({
  provider: "slack",
  tenantId: "org_acme",
  userId: "user_jane",
  redirectUrl: "https://yourapp.com/integrations/callback",
  scopes: ["channels:read", "chat:write", "users:read"], // optional override
});

// Redirect user to session.authorization_url

Go

session, err := client.CreateAuthSession(ctx, &authpipe.CreateAuthSessionParams{
  Provider:    "slack",
  TenantID:    "org_acme",
  UserID:      "user_jane",
  RedirectURL: "https://yourapp.com/integrations/callback",
  Scopes:      []string{"channels:read", "chat:write", "users:read"},
})

Python

session = client.create_auth_session(
    provider="slack",
    tenant_id="org_acme",
    user_id="user_jane",
    redirect_url="https://yourapp.com/integrations/callback",
    scopes=["channels:read", "chat:write", "users:read"],
)

Parameters:

Parameter	Required	Description
provider	Yes	Provider slug (e.g., "slack", "google")
tenant_id	Yes	Your tenant identifier
redirect_url	Yes	Where to send the user after OAuth completes
user_id	No	End-user identifier (required for user-attached providers)
scopes	No	Override scopes for this session
installation_id	No	Link this connection to an existing installation
template_variables	No	Per-session template values (e.g., {"shop": "acme-store"} for Shopify)

Handle the callback

You don’t need to implement a callback endpoint. Authpipe handles the OAuth callback at oauth_redirect_url, exchanges the authorization code for tokens, encrypts and stores them, then redirects the user to your redirect_url.

After the redirect, you can optionally check the connection status:

Node

const connections = await authpipe.searchConnections({
  filter: {
    tenant_id: { eq: "org_acme" },
    user_id: { eq: "user_jane" },
  },
  sort: [{ field: "connected_at", direction: "desc" }],
  limit: 1,
});

const connection = connections.data[0];
console.log(connection.status); // "active"

Go

resp, err := client.SearchConnections(ctx, &authpipe.SearchRequest{
  Filter: map[string]map[string]interface{}{
    "tenant_id": {"eq": "org_acme"},
    "user_id":   {"eq": "user_jane"},
  },
  Sort:  []authpipe.SortDirective{{Field: "connected_at", Direction: "desc"}},
  Limit: 1,
})

Python

from authpipe.types import SearchRequest, SortDirective

resp = client.search_connections(SearchRequest(
    filter={"tenant_id": {"eq": "org_acme"}, "user_id": {"eq": "user_jane"}},
    sort=[SortDirective(field="connected_at", direction="desc")],
    limit=1,
))

Retrieve credentials

Once a connection exists, call getCredential to get a valid access token.

Node

const { credential, source, scopes } = await authpipe.getCredential({
  provider: "slack",
  tenantId: "org_acme",
  userId: "user_jane",
});

// credential is a valid access token
// source is "connection" or "installation"

Go

result, err := client.GetCredential(ctx, &authpipe.GetCredentialParams{
  Provider: "slack",
  TenantID: "org_acme",
  UserID:   "user_jane",
})
// result.Credential, result.Source

Python

result = client.get_credential(
    provider="slack",
    tenant_id="org_acme",
    user_id="user_jane",
)
# result.credential, result.source

If the token is expired, Authpipe refreshes it transparently before returning.

Re-authorization

If a user re-authorizes (e.g., to upgrade scopes), Authpipe upserts the existing connection rather than creating a duplicate. The tokens and scopes are updated in place.

Revoking connections

Node

await authpipe.deleteConnection("conn_abc123");

Go

err := client.DeleteConnection(ctx, "conn_abc123")

Python

client.delete_connection(connection_id="conn_abc123")

This sets the connection status to revoked. The connection can be reactivated if the user re-authorizes.