pxy / docs

From sign-in to API request.

Your backend uses a pxy project key. Your users approve access through a hosted provider sign-in.

1. Get access to a project

Contact the operator for the CLI, a project and a scoped key. Keep that key in your backend and load it from a private file or standard input.

pxy --endpoint https://app.pxy.sh --project PROJECT_ID --environment production login --token-file /private/path/pxy-token

2. Ask a user to connect

pxy connect gmail --external-user user_123

The CLI opens and prints a hosted approval URL, then waits for the connection. The user sees the requesting application and access before signing in with the provider. Treat the temporary approval URL as a secret.

For a remote or headless flow, use --no-browser --no-wait --json, then resume with pxy connect wait SESSION_ID.

3. Call the native API

pxy connections inspect CONNECTION_ID --json
pxy proxy CONNECTION_ID GET /gmail/v1/users/me/profile
pxy connections disconnect CONNECTION_ID

Requests are limited to the connection’s granted access and supported destinations. Provider errors and throttling remain visible. A timed-out write may have completed upstream; inspect the outcome before retrying.

Calling from your backend

Authenticate with Authorization: Bearer <project key>. Set X-Pxy-Project and X-Pxy-Environment. Create a hosted session at POST /v1/connect-sessions for the integration and external user, then poll that session’s ID. Native requests use /v1/proxy/<connection ID>/<provider path>.

Access is arranged with the operator. Examples describe the interface; managed-provider availability depends on the configured registration, required reviews and successful live validation.