Start here · v1

Make your first request

Start with a read-only request. You need an approved OrcheSphere account, current company access and Node.js 22 or later for the sample client.

1. Register your application. Open API & developers in the signed-in portal. Choose a name, an exact redirect URI and the minimum scopes. For the local example, register http://127.0.0.1:8788/callback with orchesphere.read and offline_access.
2. Run the PKCE example. Clone the public repository and set your assigned client ID. The example keeps pending state and tokens in process memory.

git clone https://github.com/PlatformzHQ/orchesphere-api.git
cd orchesphere-api
export ORCH_CLIENT_ID="orch_app_YOUR_REGISTERED_ID"
node examples/oauth-client.mjs

3. Open the authorization URL. The example prints a URL, not a token. Sign in on orchesphere.ai and review the application, scopes and resource. The local callback validates the returned state and issuer before exchanging its one-time code.
4. Read your workspaces. The example calls GET /v1/workspaces, reports the number returned, demonstrates refresh and revokes its refresh token before exiting.

The request

GET /v1/workspaces HTTP/1.1
Host: api.orchesphere.ai
Authorization: Bearer <access_token>
Accept: application/json

The response contains only the companies currently assigned to the consenting user. Use a returned workspace ID for later requests; a guessed ID does not grant access.

Next steps