ArchAstro

ArchAstro

Developer Docs

Extensions & Integrations

Connect OAuth providers, configure webhooks, and build agent capabilities with tools and connectors.

Overview

ArchAstro treats integrations as first-class platform primitives. Agents access external services through installations (scoped data connections), users authorize access through OAuth connectors, and external systems push events via webhooks.

This page covers the integration surface end-to-end: OAuth setup, connector flows, webhook configuration, and the tools that agents use to act on connected data.

OAuth providers

Supported providers

Provider Key What agents can access
Google google Gmail, Calendar, Drive
Microsoft microsoft Outlook, Calendar, OneDrive
GitHub github Repos, Issues, PRs, Actions
Slack slack Channels, Messages, Users
X (Twitter) x_twitter Posts, DMs, Timelines

Setting up OAuth in the portal

  1. Go to OAuth → Providers under your app
  2. Click Configure on the provider you want
  3. Enter the Client ID and Client Secret from the provider's developer console
  4. The platform auto-configures callback URLs and scopes
  5. Save the configuration

Once configured, users in your app can connect their accounts through the connector OAuth flow.

Connector flow (user-facing)

The connector flow is how end users authorize access to their external accounts. The SDK handles this end-to-end:

import { buildConnectorAuthorizeUrl } from "@archastro/sdk";

// Generate the OAuth authorization URL
const url = await buildConnectorAuthorizeUrl("google", {
  restApi: client.rest,
  teamId: teamId,
  accessLevel: "full_access",
  webRedirect: "https://yourapp.com/auth/callback",
});

// Redirect the user to `url`
// After authorization, they're redirected back to your app

Check connection state:

const state = await client.rest.getConnectorState("google", teamId);
// { connected: true, scopes: ["gmail.readonly", "calendar.events"], ... }

Or check per-user:

const state = await client.rest.getUserConnectorState("google");

Disconnect:

await client.rest.disconnectConnector("google", { teamId });

OAuth API endpoints

User-scoped connector endpoints:

GET  /api/v2/users/:user_id/connectors/:provider/state    # Check state
POST /api/v2/users/:user_id/connectors/:provider/handoff   # Start OAuth
DELETE /api/v2/users/:user_id/connectors/:provider          # Disconnect

Team-scoped connectors use the same pattern under /api/v2/teams/:team_id/connectors/.

Handoff request:

{
  "access_level": "readwrite",
  "services": ["gmail", "calendar"],
  "return_to": "/account"
}

Returns { authorize_url: "https://accounts.google.com/..." } — redirect the user there.

Browser-based OAuth endpoints:

GET /auth/:provider                         # Start OAuth login
GET /auth/:provider/callback                # OAuth callback
GET /auth/federated/:provider/authorize     # Federated OAuth
GET /auth/federated/:provider/callback      # Federated callback
GET /connect/:provider/authorize            # Connector OAuth
GET /connect/:provider/callback             # Connector callback

OAuth server endpoints:

GET  /oauth/scopes                          # List available scopes
POST /oauth/token                           # Exchange tokens
POST /oauth/device/authorize                # Device flow start
POST /oauth/device/approve                  # Approve device

GitHub App integration

GitHub App integration provides a deeper connection to GitHub than the standard OAuth connector. Instead of acting on behalf of a single user, a GitHub App is installed at the organization or repository level and receives events and permissions independently.

How it works

  1. The developer registers a GitHub App in the GitHub developer settings
  2. The developer configures the GitHub App's webhook URL to point to ArchAstro (see below)
  3. A user installs the GitHub App on their GitHub org or repos
  4. GitHub sends installation and repository events to ArchAstro
  5. ArchAstro links the GitHub installation to your app
  6. Connected agents can use GitHub capabilities based on the installation's permissions

Installation record

GitHub App installations use the following kind and category:

Field Value
kind integration/github_app
category integration
requires_integration true

Because requires_integration is true, the installation only activates after a matching integration is connected with valid credentials.

Webhook processing

GitHub App events are delivered to a global endpoint rather than the per-app webhook endpoint used by standard provider webhooks:

POST /webhooks/github_app

Verification: Every incoming request is verified using HMAC-SHA256. The platform computes the signature over the raw request body using the GitHub App's webhook secret and compares it against the X-Hub-Signature-256 header. Requests that fail verification are rejected with a 401.

After verification, ArchAstro processes events asynchronously by type (installation, push, pull_request, issues, etc.). Common event flows:

  • installation / installation_repositories — creates or updates Integration records when users install or modify the app
  • push — triggers source ingestion for connected repositories
  • pull_request / issues — can trigger agent routines or update context items

GitHub capabilities for agents

When a GitHub App installation is active, ArchAstro makes GitHub capabilities available to the agent automatically based on installation scope and permissions.

If an agent has both a custom tool and an auto-provided GitHub capability with the same function, the custom tool is used.

Example of tools that might be derived from a GitHub App installation:

Tool key Description
github_create_issue Create an issue in a connected repository
github_list_pull_requests List open PRs for a repository
github_get_file_contents Read file contents from a branch
github_create_comment Comment on an issue or PR

These capabilities are available without extra setup once the GitHub App installation is active and credentials are valid.

Comparison with OAuth connector

OAuth connector (github) GitHub App (integration/github_app)
Auth scope Per-user Per-org or per-repo
Token type User OAuth token App installation token
Receives webhooks Via standard webhook config Via global /webhooks/github_app endpoint
Best for User-scoped actions (PRs, commits as user) Org-wide automation (CI, bots, repo management)

Use the OAuth connector when agents need to act as a specific user. Use the GitHub App integration when agents need org-level access or need to receive repository events.

Slack Bot

The ArchAstro Slack Bot brings your agents directly into Slack. Once an org admin installs the bot, team members can talk to agents by mentioning @archastro in any channel — no per-channel setup required.

Installing the bot

An org admin connects the bot from the Context → Integrations page in the developer portal by clicking Connect Slack. This redirects to Slack's OAuth consent screen. After approval, the bot is installed in the workspace and appears as a new integration in the list.

Once installed, invite @archastro to the Slack channels where you want agents to be available.

Talking to agents

Mention @archastro followed by an agent name and your message:

@archastro @DeployBot what's the status of the staging deploy?

The bot immediately shows a thinking indicator while the agent processes the request, then replaces it with the real response.

If you don't specify an agent name, the bot checks whether the channel has a default agent configured. If no agent matches, the bot replies with a list of available agents and example syntax.

What the bot supports

  • Thinking indicator — immediate feedback while the agent works, replaced in-place with the answer
  • Formatted responses — AI markdown is converted to Slack's native formatting (bold, italic, links, headings, code blocks)
  • Per-user memory — each Slack user is mapped to their own identity so agents remember context per person
  • Agent name display — responses appear under the agent's name (e.g., "DeployBot") rather than a generic bot name
  • Proactive messages — agents can broadcast scheduled or event-driven messages to configured Slack channels

Slack Bot vs. Slack OAuth connector

OAuth connector (slack) Slack Bot (slack_bot)
Purpose Read a user's Slack history as agent context Two-way agent conversations in Slack
Installed by Individual users Org admin (once per workspace)
Use case Search past messages, channels, DMs Ask agents questions, receive answers in Slack

Use the OAuth connector when agents need to search a user's Slack data. Use the Slack Bot when you want agents to be accessible directly in Slack channels.

Webhooks

Webhooks let external systems push events to your app. ArchAstro supports provider-specific webhooks with built-in signature validation and generic webhooks for any system.

Provider webhooks

Provider webhooks have built-in signature verification:

  • GitHub — validates X-Hub-Signature-256
  • Slack — validates Slack signing secret

Create a provider webhook:

curl -X POST "https://api.archastro.ai/protected/api/v2/developer/apps/${ARCHASTRO_APP_ID}/webhooks" \
  -H "Authorization: Bearer ${ARCHASTRO_SECRET_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "github",
    "signing_secret": "whsec_..."
  }'

Generic webhooks

Generic webhooks work with any system that can POST JSON. Instead of a provider, you specify a lookup_key:

curl -X POST "https://api.archastro.ai/protected/api/v2/developer/apps/${ARCHASTRO_APP_ID}/webhooks" \
  -H "Authorization: Bearer ${ARCHASTRO_SECRET_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "lookup_key": "billing-events",
    "signing_secret": "'"${BILLING_WEBHOOK_SECRET}"'"
  }'

Use generic webhooks for third-party vendors, CRM systems, payment processors, and any service that can POST JSON.

Inbound delivery

All webhooks (provider and generic) are delivered to:

POST /webhooks/:app_id/:provider_or_key

ArchAstro validates signatures, stores delivery events, and processes them asynchronously. Failed events are retried.

Webhook management API

GET    /protected/api/v2/developer/apps/:app_id/webhooks
POST   /protected/api/v2/developer/apps/:app_id/webhooks
GET    /protected/api/v2/developer/apps/:app_id/webhooks/:id
PATCH  /protected/api/v2/developer/apps/:app_id/webhooks/:id
DELETE /protected/api/v2/developer/apps/:app_id/webhooks/:id
GET    /protected/api/v2/developer/apps/:app_id/webhooks/:id/events

Webhook management via CLI

archastro list appwebhooks
archastro create appwebhook -p github -s my_signing_secret
archastro describe appwebhook webhook_abc123
archastro update appwebhook webhook_abc123 --enabled false
archastro delete appwebhook webhook_abc123

Integration actions

Once a user has connected a provider, agents can execute actions on the connected service:

// List connected integrations
const integrations = await client.rest.listIntegrations();

// List available actions for a provider
const actions = await client.rest.listProviderActions("google");

// Execute an action
await client.rest.runAction("google", "send_email", {
  to: "user@example.com",
  subject: "Follow-up",
  body: "Here's the information you requested.",
});

For the exact currently published external API surface for integrations and connector operations, use /openapi.json.

OAuth clients (third-party apps)

If you want third-party applications to authenticate against your ArchAstro app using OAuth, enable third-party OAuth in the portal:

  1. Go to OAuth → Clients
  2. Toggle Enable Third-Party OAuth
  3. Click Register Client
  4. Enter client name, scopes, and redirect URIs
  5. Copy the client credentials (shown once)

Registered clients can then use standard OAuth flows to obtain tokens scoped to your app.

How integrations connect to agents

The full integration flow for an agent:

1. Developer configures OAuth provider (portal)
2. Developer creates an installation on an agent (kind: integration/gmail)
3. User completes OAuth connector flow (browser)
4. Platform stores encrypted credentials (Integration record)
5. Installation activates → Sources auto-created
6. Sources begin ingesting data (emails, events, repos)
7. Agent's context fills with searchable items
8. Agent can now search and act on the connected data

This architecture separates concerns clearly:

  • OAuth providers — configured once per app by the developer
  • Installations — connect a specific agent to a specific data source
  • Integrations — store per-user OAuth credentials
  • Sources — track individual data retrieval tasks
  • Tools — let agents take actions on connected services