Your sandbox

### Client libraries

If your agent already uses a vendor's client library, keep it. Give it the app's address and token instead of the real service's, and nothing else in your code changes. This page lists the one setting each library needs.

### At a glance

Each library below, but Meta's, Stripe's, HubSpot's and GitHub's, was tested against a run served over HTTPS exactly as hosted runs are, with reads and writes: queries, lists across several pages, creates and updates. Stripe's and HubSpot's were tested the same way on a run served over plain HTTP. GitHub's were tested against the GitHub twin directly, with queries, creates and lists across several pages: Octokit, PyGithub and githubkit over plain HTTP and over HTTPS, and gh through a local socket, without TLS.

| App | Library | Tested | What to set |
| --- | --- | --- | --- |
| Slack | slack\_sdk (Python) | 3.46.0 | base\_url |
| Slack | @slack/web-api (Node) | 8.3.0 | slackApiUrl |
| Google | google-api-python-client | 2.201.0 | discoveryServiceUrl and static\_discovery=False |
| Google | googleapis (Node) | 189.0.0 | rootUrl |
| Salesforce | simple-salesforce | 1.12.10 | instance\_url , version |
| Salesforce | jsforce (Node) | 3.13.1 | instanceUrl , version |
| Shopify | ShopifyAPI (Python) | 12.7.0 | Session.myshopify\_domain . GraphQL only. |
| Shopify | @shopify/admin-api-client | 2.0.1 | storeDomain |
| Zendesk | zenpy | 2.0.57 | subdomain and domain |
| Zendesk | node-zendesk | 6.0.1 | endpointUri |
| WhatsApp | facebook-business (Python) | 26.0.2, against the twin | session.GRAPH |
| Stripe | stripe (Python) | 16.0.1, over HTTP | base\_addresses |
| HubSpot | hubspot-api-client (Python) | 13.0.0, over HTTP | host |
| GitHub | octokit (Node) | 5.0.5, against the twin | baseUrl |
| GitHub | gh (command line) | 2.101.0, without TLS | GH\_HOST , GH\_ENTERPRISE\_TOKEN |
| GitHub | PyGithub (Python, community) | 2.10.0, against the twin | base\_url |
| GitHub | githubkit (Python, community) | 0.17.1, against the twin | base\_url |

The examples read the app as in Apps and credentials : app(name) is one of the run's apps and credential(name, kind) one of its tokens. The same works on what client.connect() returns in edit mode, or on run.apps in Python. In Node:

run.js

const

run = JSON.

parse

(

require

(

"fs"

).

readFileSync

(process.env.STATEWEAVE\_RUN\_FILE,

"utf8"

));

const

app = (name) =&gt; run.apps\[name\];

const

credential = (name, kind =

"user"

) =&gt; Object.

entries

(

app

(name).credentials).

find

((\[label\]) =&gt; label.

split

(

":"

)\[

0

\] === kind)\[

1

\];

The Node examples use await . In a CommonJS file, where require works, put them inside an async function.

### From environment variables

With the STATEWEAVE\_\* variables instead (from sw sandbox connect p-… --env , a twin run's .env , or run.env ), build each endpoint from the app's address. STATEWEAVE\_&lt;APP&gt;\_URL has no trailing slash; Apps and credentials lists each app's API root.

Python

import

os

from

slack\_sdk

import

WebClient slack =

WebClient

(token=os.environ\[

"STATEWEAVE\_SLACK\_USER\_TOKEN"

\], base\_url=os.environ\[

"STATEWEAVE\_SLACK\_URL"

\] \+

"/api/"

)

### Slack

from

slack\_sdk

import

WebClient slack =

WebClient

(token=

credential

(

"slack"

,

"user"

), base\_url=

app

(

"slack"

)\[

"endpoints"

\]\[

"web\_api"

\])

const

\{ WebClient \} =

require

(

"@slack/web-api"

);

const

slack =

new

WebClient

(

credential

(

"slack"

,

"user"

), \{ slackApiUrl:

app

(

"slack"

).endpoints.web\_api \});

### Google

The same setting serves Gmail, Calendar, Sheets and Drive. Python's library ships its own copy of each API description, so turn that off and point it at the app's. Node's takes the app's address as rootUrl , with a trailing slash.

from

google.oauth2.credentials

import

Credentials

from

googleapiclient.discovery

import

build gmail =

build

(

"gmail"

,

"v1"

, credentials=

Credentials

(

credential

(

"gmail"

)), discoveryServiceUrl=

app

(

"gmail"

)\[

"endpoints"

\]\[

"discovery"

\], static\_discovery=

False

)

const

\{ google \} =

require

(

"googleapis"

);

const

auth =

new

google.auth.

OAuth2

(); auth.

setCredentials

(\{ access\_token:

credential

(

"gmail"

) \});

const

gmail = google.

gmail

(\{ version:

"v1"

, auth, rootUrl:

app

(

"gmail"

).base\_url \+

"/"

\});

For Sheets, list spreadsheets through Drive with the Sheets app's own token and its drive\_discovery (Python) or the same rootUrl (Node).

### Salesforce

Pass the version the app's rest\_api names ( 68.0 ), not the library's default.

from

simple\_salesforce

import

Salesforce sf =

Salesforce

(instance\_url=

app

(

"salesforce"

)\[

"endpoints"

\]\[

"instance\_url"

\], session\_id=

credential

(

"salesforce"

), version=

"68.0"

) accounts = sf.

query

(

"SELECT Id, Name FROM Account LIMIT 10"

)\[

"records"

\]

const

jsforce =

require

(

"jsforce"

);

const

conn =

new

jsforce.

Connection

(\{ instanceUrl:

app

(

"salesforce"

).endpoints.instance\_url, accessToken:

credential

(

"salesforce"

), version:

"68.0"

, \});

const

accounts = (

await

conn.

query

(

"SELECT Id, Name FROM Account LIMIT 10"

)).records;

### Shopify

StateWeave's Shopify serves the GraphQL Admin API . The REST Admin API (paths such as /admin/api/2026-10/products.json ) answers 404 with the header x-twin-not-implemented: 1 , so use a library's GraphQL client.

import

shopify host =

app

(

"shopify"

)\[

"base\_url"

\].

removeprefix

(

"https://"

)

\# t-….app.stateweave.net

shop, \_, domain = host.

partition

(

"."

) shopify.Session.myshopify\_domain = domain

\# the library appends this to the shop's name

session = shopify.

Session

(shop,

"2026-10"

,

credential

(

"shopify"

,

"app"

)) shopify.ShopifyResource.

activate\_session

(session) result = shopify.

GraphQL

().

execute

(

"\{ shop \{ name \} orders(first: 10) \{ nodes \{ name \} \} \}"

)

const

\{ createAdminApiClient \} =

require

(

"@shopify/admin-api-client"

);

const

shopify =

createAdminApiClient

(\{ storeDomain:

app

(

"shopify"

).base\_url.

replace

(

"https://"

,

""

), apiVersion:

"2026-10"

, accessToken:

credential

(

"shopify"

,

"app"

), \});

const

\{ data \} =

await

shopify.

request

(

"\{ shop \{ name \} orders(first: 10) \{ nodes \{ name \} \} \}"

);

ShopifyAPI builds its own address. Given any shop name, it keeps the first label and adds .myshopify.com . Without Session.myshopify\_domain set, your agent would call a real Shopify store, not StateWeave. Its REST resources ( shopify.Product , shopify.Order , …) use the REST Admin API and fail with ResourceNotFound .

### Zendesk

from

zenpy

import

Zenpy host =

app

(

"zendesk"

)\[

"base\_url"

\].

removeprefix

(

"https://"

)

\# t-….app.stateweave.net

subdomain, \_, domain = host.

partition

(

"."

) zendesk =

Zenpy

(subdomain=subdomain, domain=domain, oauth\_token=

credential

(

"zendesk"

))

const

zendesk =

require

(

"node-zendesk"

);

const

client = zendesk.

createClient

(\{ endpointUri:

app

(

"zendesk"

).endpoints.rest\_api.

replace

(

/\\/$/

,

""

), token:

credential

(

"zendesk"

), oauth:

true

, \});

### WhatsApp

Meta publishes no maintained WhatsApp messaging SDK, so messages go over plain HTTP (see WhatsApp ). Meta's business SDK, facebook-business , covers the account's objects: WhatsApp Business accounts, templates, phone numbers. Set the address it calls instead of graph.facebook.com on the session.

Python

from

facebook\_business.api

import

FacebookAdsApi

from

facebook\_business.adobjects.whatsappbusinessaccount

import

WhatsAppBusinessAccount

from

facebook\_business.session

import

FacebookSession session =

FacebookSession

(access\_token=

credential

(

"whatsapp"

,

"bot"

)) session.GRAPH =

app

(

"whatsapp"

)\[

"base\_url"

\]

\# no trailing slash, like https://graph.facebook.com

api =

FacebookAdsApi

(session, api\_version=

"v26.0"

) templates =

WhatsAppBusinessAccount

(waba\_id, api=api).

get\_message\_templates

(fields=\[

"name"

,

"status"

\])

waba\_id is the WhatsApp Business account's id, found as in Apps and credentials . For anything the SDK has no class for, use api.call("POST", (phone\_number\_id, "messages"), params=\{…\}) . This library was checked against the WhatsApp twin directly, over plain HTTP, not through a hosted run.

### Stripe

Python

import

stripe base =

app

(

"stripe"

)\[

"base\_url"

\] client = stripe.

StripeClient

(

credential

(

"stripe"

), base\_addresses=\{

"api"

: base,

"files"

: base,

"connect"

: base,

"meter\_events"

: base\})

for

customer

in

client.v1.customers.

list

(\{

"limit"

:

100

\}).

auto\_paging\_iter

():

print

(customer.id, customer.email)

Stripe's library calls four hosts, api.stripe.com and three others: base\_addresses sends each of them to the app.

### HubSpot

Python

import

hubspot api = hubspot.Client.

create

(access\_token=

credential

(

"hubspot"

,

"app"

), host=

app

(

"hubspot"

)\[

"base\_url"

\]) contacts = api.crm.contacts.

get\_all

(properties=\[

"email"

,

"firstname"

\])

\# every page

host takes the app's address as it is, with no trailing slash, in place of https://api.hubapi.com . Use the Service Key ( app ): a blank sandbox's HubSpot has no user: credential.

### GitHub

GitHub's own clients are Octokit, for JavaScript (shown here), Ruby and .NET, and the gh command line. GitHub publishes no Python library; PyGithub and githubkit are community ones. The examples write to owner/support-bot , the repository the example in Apps and credentials makes: in a blank sandbox, run that one first.

const

\{ Octokit \} =

require

(

"octokit"

);

const

octokit =

new

Octokit

(\{ baseUrl:

app

(

"github"

).base\_url, auth:

credential

(

"github"

) \}); octokit.hook.

before

(

"request"

, (options) =&gt; \{ options.headers\[

"x-github-api-version"

\] =

"2022-11-28"

; \});

await

octokit.rest.issues.

create

(\{ owner:

"owner"

, repo:

"support-bot"

, title:

"Checkout page times out"

\});

const

issues =

await

octokit.

paginate

(octokit.rest.issues.listForRepo, \{ owner:

"owner"

, repo:

"support-bot"

, per\_page:

100

\});

const

\{ viewer \} =

await

octokit.

graphql

(

"\{ viewer \{ login \} \}"

);

from

github

import

Auth, Github g =

Github

(base\_url=

app

(

"github"

)\[

"base\_url"

\], auth=Auth.

Token

(

credential

(

"github"

))) repo = g.

get\_repo

(

"owner/support-bot"

) repo.

create\_issue

(title=

"Checkout page times out"

)

for

issue

in

repo.

get\_issues

(state=

"open"

):

\# every page

print

(issue.number, issue.title)

from

githubkit

import

GitHub github =

GitHub

(

credential

(

"github"

), base\_url=

app

(

"github"

)\[

"base\_url"

\]) github.rest.issues.

create

(

"owner"

,

"support-bot"

, title=

"Checkout page times out"

)

for

issue

in

github.rest.

paginate

(github.rest.issues.list\_for\_repo, owner=

"owner"

, repo=

"support-bot"

):

print

(issue.number, issue.title)

Octokit takes the app's address with no trailing slash as baseUrl . With a slash it asks for //repos/… , and every call answers 404. Without an X-GitHub-Api-Version header, a few writes, issues.create among them, answer with a Deprecation header and Octokit prints a warning; the hook above sends the version. octokit 5 is an ES module: require loaded it on Node 25.8, and where require cannot load an ES module, load it with await import("octokit") inside the async function.

PyGithub and githubkit take the address as base\_url , with or without a trailing slash. githubkit sends X-GitHub-Api-Version: 2026-03-10 , which the app serves.

Release uploads go to another host. Octokit's repos.uploadReleaseAsset sends the file to uploads.github.com unless you pass the release's upload\_url as url ; without it, your agent would call the real GitHub with its token. githubkit's repos.upload\_release\_asset posts to the API's address, which answers 501: upload through a second client, GitHub(token, base\_url=release.upload\_url.split("/repos/")\[0\]) . PyGithub's upload\_asset follows upload\_url by itself.

### gh

gh reaches the app as it reaches a GitHub Enterprise Server host: give it the address's host as GH\_HOST and the token as GH\_ENTERPRISE\_TOKEN ( gh uses GH\_TOKEN only for github.com and ghe.com). It then calls …/api/v3/ and …/api/graphql , which the app serves.

Shell

export

GH\_HOST=

"$\{STATEWEAVE\_GITHUB\_URL\#https://\}"

GH\_ENTERPRISE\_TOKEN=

"$STATEWEAVE\_GITHUB\_USER\_TOKEN"

GH\_TELEMETRY=0 gh api user

--jq

.login gh issue create

-R

"$GH\_HOST/owner/support-bot"

--title

"Checkout page times out"

--body

"Seen on mobile"

gh issue list

-R

"$GH\_HOST/owner/support-bot"

GH\_TELEMETRY=0 turns gh 's telemetry off. gh was tested through a local socket, so its paths and its token were checked, but not its TLS connection to a hosted run.

### Other libraries

Any library works if it lets you set where it sends requests and which token it uses. Watch for two things:

A hard-coded host. Some libraries build the address from an account or shop name, like ShopifyAPI above. Find the setting that changes the domain; without one, the library can't reach StateWeave.

Its own sign-in. A run hands over access tokens, not client secrets or refresh tokens. Give the library the token directly instead of running its OAuth flow.

Tell us at support@stateweave.net if a library you use doesn't work.

[Apps and credentials](https://stateweave.net/docs/apps)

[Apps and credentials](https://stateweave.net/docs/apps#whatsapp)

[Apps and credentials](https://stateweave.net/docs/apps#github)