Skip to content
Docs

Connect a tool that hands over its own key

POST
/api/workspaces/{ws}/install/{type}

For catalog entries with install (WooCommerce): values holds the fields it names (the store's address). Makes the connection (status: "pending") and answers the tool's own approve page. Once approved, the tool sends Roster a fresh key, which is checked and kept sealed, and people come back to returnTo (a path in the app) with oauth=connected; a denial, or a key that never arrives, removes the pending connection. With connectionId, reconnects that connection instead. Owners and admins only.

Authorization

session
cookiebetter-auth.session_token<token>

Set by POST /api/auth/sign-in/email.

Path Parameters

ws*string

The workspace id (from GET /api/me).

type*string

The tool, e.g. linear.

Request Body

application/json
  1. body
values*
returnTo?string
connectionId?string

Response Body

{ url }: send the person there.

application/json
Example Request
curl -X POST 'https://app.useroster.work/api/workspaces/string/install/string' \  -H 'Content-Type: application/json' \  -d '{  "values": {    "property1": "string",    "property2": "string"  }}'
Example Response
{  "url": "https://shop.example.com/wc-auth/v1/authorize?app_name=Roster&scope=read_write&…"}

Connect a tool in one click POST

For catalog entries with `oneClick: true`: makes the connection (`status: "pending"`) and answers the tool's page to approve it; afterwards the tool sends people back to `returnTo` (a path in the app), connected. Cancelling there removes the pending connection. With `connectionId`, reconnects that connection instead.

Test a connection and find its tools POST

For MCP servers and custom APIs (catalog entries with `discovers: true`): asks the MCP server for its tools, or reads the API's OpenAPI document (its `openapiUrl`, or the text given as `document`). What's found is kept on the connection as `settings.discovered`, each tool with `readOnly` (from the server's `readOnlyHint`, or GET); tools the server doesn't mark count as changing things. A custom API with no document is checked with one GET of its base address.