SDKs
Parallel Works publishes official client libraries for the ACTIVATE REST API in three languages:
- TypeScript —
@parallelworks/clienton npm, with optional SWR hooks for React - Python —
parallelworks-clienton PyPI, with sync and async support - Go —
github.com/parallelworks/sdk/go
All three SDKs are generated from the same OpenAPI specification that powers the API reference, so every endpoint is available with full type definitions.
Authentication
The Go, Python, and TypeScript SDKs handle OAuth access tokens and renewal automatically when you use CLI credential config after signing in with pw auth. The SDK authenticates requests through your saved sign-in; your application does not need to copy access tokens or implement refresh logic.
Choose how the client should obtain credentials:
| Use case | Create the client from | Renewal |
|---|---|---|
| A notebook, local tool, or long-running script you run yourself | CLI credential config after pw auth | Automatic OAuth access-token renewal through the CLI while the sign-in is valid. |
| CI, cron, or a persistent unattended service | An API key supplied by your secret store | No automatic renewal; replace the key before expiry and recreate the client. |
| A one-off call using a copied OAuth access token | The raw credential | No automatic renewal; the client uses that value until it expires or is revoked. |
See Authentication for CLI and scripts for the full decision guide and operational examples.
Signed in with pw auth
First, sign in with pw auth, then use the credential-config constructor for your SDK. The SDK obtains and caches an OAuth access token and asks the CLI for a replacement before it expires by running pw auth token --print -o json. Keep the CLI installed and on your PATH. The SDK does not open the initial sign-in flow for you; if the saved sign-in expires or is revoked, sign in again.
| SDK | Create the client |
|---|---|
| Go | parallelworks.NewClientFromCredentialConfig() |
| Python | Client.from_credential_config() |
| TypeScript | Client.fromCredentialConfig() (Node.js 20.16 or later) |
The client uses the same credential selection as the CLI: PW_API_KEY if set, then the context you name, PW_CONTEXT, and the current context. A nonempty PW_API_KEY bypasses the saved sign-in even when you name a context. Unset it when you want the SDK to renew your browser or device sign-in.
Long-running clients and separate credentials
Keep one credential-config client for the life of your script; it obtains new tokens as needed. Do not copy pw auth token --print into PW_API_KEY or pass it to a raw-credential constructor expecting renewal. A saved API key stays a fixed credential, regardless of its chosen lifetime, even when loaded from credential config.
All three SDKs honor PW_CREDENTIALS_DIR: set it before creating the client to use $PW_CREDENTIALS_DIR/.credentials. The CLI subprocess inherits it, so it reads and updates the same credentials. Use a writable directory and the same OS user and credential-store access as the original sign-in. See credential-directory recipes before moving credentials into a container or shared home.
A browser or device sign-in still has idle and maximum lifetime limits and can be revoked. If it ends, sign in again using the same directory and context, then retry the failed work. Use API keys with planned rotation for services that cannot wait for a person to sign in.
API keys
The Token option in Account > Authentication creates a short-lived API key. Use it with the SDK exactly like any other API key; its expiration does not make it a separate authentication method.
For CI and other automation that runs without you, use an API key (pwt_...). Create it in your account settings. By default, its chosen expiration must be within 730 days; your organization or platform policy can change the limit, and only Unlimited permits non-expiring keys. Follow the key rotation steps for persistent jobs. An API key contains your platform host, so each SDK can create a client from the key alone, with no URL required. Each SDK also accepts an explicit platform host.
Note
Treat API keys and OAuth access tokens with the same care as your login password. Store them in environment variables or a secrets manager rather than committing them to source control.
Next Steps
- TypeScript — Install and use
@parallelworks/client - Python — Install and use
parallelworks-client - Go — Install and use the Go client
- API Reference — Browse every endpoint, with schemas and examples