OAuth apps for the Voholabs Studio API

Use an OAuth app when your product needs to post for people who have their own Studio accounts. To automate your own workspace, your API key is simpler.

How do I create an OAuth app?#

1. In Studio, open Settings › Connect Agent and choose the Apps tab.
2. Fill in App Name (up to 100 characters), an optional Description (up to 500) and Profile Picture, and the Redirect URL your users return to.
3. Create the app. Studio shows your client ID, which starts with pca_, and your client secret, which starts with pcs_.
4. Copy the client secret straight away. Studio only shows it once.

How does a user authorise my app?#

1. Send the user to the consent page:

   https://studio.voholabs.com/oauth/authorize?client_id=YOUR_CLIENT_ID&response_type=code&state=RANDOM_STATE

   response_type must be code. Use state to tie the answer to the user's session.

2. The user signs in to Studio if needed, sees your app's name, description and picture, and approves or denies.

3. Studio sends the user back to your redirect URL. On approval it carries ?code=...&state=...; on denial ?error=access_denied&state=....

4. Exchange the code within 10 minutes, from your server:

   curl https://studio.voholabs.com/api/oauth/token \
     -H "Content-Type: application/json" \
     -d '{
       "grant_type": "authorization_code",
       "code": "THE_CODE",
       "client_id": "YOUR_CLIENT_ID",
       "client_secret": "YOUR_CLIENT_SECRET"
     }'

5. Store the access_token from the response. It starts with pos_. The response also returns the workspace ID as id, and token_type is bearer.

How do I call the API with a token?#

Use the token exactly where an API key would go.

• Public API: send it on its own in the header, Authorization: pos_.... See the public API.
• MCP server: send Authorization: Bearer pos_.... See the MCP server.
• CLI: set VOHOLABS_API_KEY to the token. See the CLI.

How does a user disconnect my app?#

In Settings › Approved Apps, which lists the applications they have authorised. Revoking stops the token immediately, so handle HTTP 401 "Invalid OAuth token" by asking the user to authorise again.