Every sample on every page follows this. Change it any time.

Get a test key
BashBrainTeammatesPricingDevelopersGet a test key

Connected apps

The apps each user connects through a sign-in link, and the apps they may choose from.

Send Authorization: Bearer vk_test_... on every call. Every route of Connected apps.

POST/v1/connectionsGet a connect link for one app, for one user (user_id) or the company's own Bash.

After consent the user lands on your return_url (or your first allowed one, or our own page), and a webhook fires. The link carries the id of the connection it makes.

Your API key, scope runtime or all. On the card: connect. Every call here is a checked sample.

Request5 fields

Headers

Idempotency-KeystringSend the same key to retry this call safely for 24 hours.
Type
string

Body

user_idstringWhose Bash: your id for the user. Absent: your company's own Bash.
Example
traveller-42
appstringrequiredThe app to connect, by its slug from GET /v1/apps.
Example
gmail
return_urlstring (URL)Where the user lands after they sign in; it must match one of your allowed return URLs. Absent: your first allowed return URL, or our own page.
Limits
At most 2048 characters.
Example
https://app.example.com/connected
deployment_idstringThe deployment whose apps decide whether this app is allowed, by its dep_ id or name. Absent: the company default's.
Limits
1 to 128 characters.
Answers 200 or 2016 fields
object"connect_link"Always connect_link.
Type
"connect_link"
idstring | nullThe connection this link makes (con_), to read with GET /v1/connections/{connection_id}; null only when there is none to make (an app with no sign-in).
Type
string | null
status"pending" | "connected"pending: send the user to url. connected: they already had this app, or it needs no sign-in.
Type
"pending" | "connected"
urlstring | nullThe sign-in link: send it to your user, or open it yourself for your company's own Bash. Null when there is nothing to sign in to.
Type
string | null
connectionobject | nullThe connection when it is already made; null while it is pending.
object"connection"Always connection.
Type
"connection"
idstringThe connection's id.
Example
con_8f2k
user_idstring | nullYour id for the user; null for your company's own Bash.
Type
string | null
appstringThe app, by its slug.
Example
gmail
status"active" | "pending" | "initializing" | "expired" | "revoked" | "inactive" | "failed"active: Bash can use it. pending or initializing: the sign-in is not finished. expired, revoked, inactive or failed: it no longer works, and the user connects it again.
Type
"active" | "pending" | "initializing" | "expired" | "revoked" | "inactive" | "failed"
labelstring | nullThe account's label, usually its email; null when the app gives none.
Type
string | null
created_atstringWhen it was connected, as an ISO 8601 date and time in UTC.
Type
string
expires_atstringWhen the link stops working, as an ISO 8601 date and time in UTC.
Type
string
TypeScript
const link = await vestra.user('traveller-42').connect('gmail');
Python
link = vestra.user("traveller-42").connect("gmail")
CLI
vestra connect gmail --user traveller-42
HTTP
# Get a sign-in link for one app. It is for one user: send them its url.curl "$VESTRA_BASE_URL/v1/connections" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "user_id": "traveller-42", "app": "gmail" }' # List their apps. You can also list the catalog your users may pick from.curl "$VESTRA_BASE_URL/v1/connections?user_id=traveller-42" \  -H "Authorization: Bearer $VESTRA_API_KEY" curl "$VESTRA_BASE_URL/v1/apps?search=calendar" \  -H "Authorization: Bearer $VESTRA_API_KEY" # Disconnect an app. user_id says whose connection it is.curl -X DELETE "$VESTRA_BASE_URL/v1/connections/con_7hs?user_id=traveller-42" \  -H "Authorization: Bearer $VESTRA_API_KEY"
MCP
{  "method": "tools/call",  "params": {    "name": "connect",    "arguments": { "user": "traveller-42", "app": "gmail" }  }}