# OAuth apps for the Voholabs Studio API

> An OAuth app lets your product act for other Studio users without asking for their API keys. Create the app in Settings › Connect Agent › Apps, send users to studio.voholabs.com/oauth/authorize, then exchange the returned code at /api/oauth/token for a pos_ token that works with the API, MCP and CLI.

Source: https://voholabs.com/docs/api/oauth  
Last updated: 5 October 2026

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](https://voholabs.com/docs/api) 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:

   ```text
   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:

   ```bash
   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`.

> [!WARNING]
> Keep the client secret and the user tokens on your server. Never put them in a browser app or a mobile app bundle.

## 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](https://voholabs.com/docs/api).
- **MCP server**: send `Authorization: Bearer pos_...`. See [the MCP server](https://voholabs.com/docs/agents/mcp).
- **CLI**: set `VOHOLABS_API_KEY` to the token. See [the CLI](https://voholabs.com/docs/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.

## Frequently asked questions

### Do OAuth tokens expire?

No. A `pos_` token stays valid until the user revokes your app in Settings › Approved Apps. There is no refresh token to manage.

### Can I ask for limited permissions?

No. The flow has no scopes. A token can do whatever the user's API key can do in the workspace they chose.

### How many OAuth apps can a workspace have?

One. Only admins of the workspace can create, edit or delete it.

### I lost my client secret. What now?

The secret is only shown when you create or rotate it. Rotate it in Settings › Connect Agent › Apps and update your server with the new one.

## Related pages

- [Public API](https://voholabs.com/docs/api)
- [Connect your agent](https://voholabs.com/docs/agents)