OAuth2

Use OAuth2 when building a third-party app that needs to access Visuary on behalf of your users. Users authorize your app with their own Visuary account and you receive an access token scoped to that user.

This follows the standard Authorization Code flow.

The authorization server metadata (endpoint URLs, supported methods) is available at:

GET https://api.visuary.com/.well-known/oauth-authorization-server

Step 1 — Register your app

In your Visuary account, open Settings → API Access
Under Developer apps, click + Create app
Fill in the registration form:

Field	Required	Description
App name	Yes	Displayed to users on the Visuary authorization screen
Redirect domain	Yes	The base URL of your app (e.g. `https://yourapp.com`). All redirect URIs used in the OAuth flow must start with this domain.
Logo	No	Shown alongside your app name on the authorization screen

After creation, copy the Client ID and Client Secret:
- Client ID — a short opaque string that identifies your app publicly; safe to include in URLs and client-side code
- Client Secret — must be kept confidential; never expose it in client-side code, mobile apps, or public repositories

Step 2 — Redirect the user to Visuary

Build the authorization URL and redirect the user's browser to it:

GET https://api.visuary.com/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &state=RANDOM_CSRF_TOKEN

Parameter	Required	Description
`response_type`	Yes	Always `code`
`client_id`	Yes	Your app's Client ID
`redirect_uri`	Yes	Must start with the redirect domain you registered
`state`	Yes	A random string you generate; returned unchanged to prevent CSRF

The user sees a Visuary login page (or is already logged in) and approves your app. Visuary redirects back to:

https://yourapp.com/callback?code=AUTH_CODE&state=RANDOM_CSRF_TOKEN

Always verify that state matches what you sent before continuing.

Step 3 — Exchange the code for an access token

Send this request from your server (never from the browser):

bash

curl -X POST https://api.visuary.com/oauth/token \
  -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=https://yourapp.com/callback"

Parameter	Required	Description
`grant_type`	Yes	Always `authorization_code`
`code`	Yes	The authorization code received in Step 2
`redirect_uri`	Yes	Must be identical to the `redirect_uri` used in Step 2. This is a security check — the server does not redirect to this URL, it only verifies it matches.

Authenticate with HTTP Basic Auth: YOUR_CLIENT_ID as the username and YOUR_CLIENT_SECRET as the password.

Response:

json

{
  "access_token": "at_...",
  "token_type": "Bearer"
}

The access token does not expire. Store it securely server-side, associated with the user who authorized it.

Use it exactly like a personal token:

bash

curl https://api.visuary.com/public/v1/workspaces \
  -H "Authorization: Bearer ACCESS_TOKEN"

Revoking access

Users can revoke your app's access at any time from Settings → API Access → Personal tokens — OAuth-issued tokens appear there alongside personal ones. Revocation is immediate.

Rotating the client secret

If your secret is compromised, go to Developer apps, open your app, and click Rotate secret. The old secret is immediately invalidated — update your server configuration before rotating to avoid downtime.

Error responses

Status	Meaning
`401`	Missing or invalid token
`403`	Token valid but no access (plan permissions or subscription level)
`400`	Bad request — check query parameters or path
`500`	Server error

OAuth2 ​

Step 1 — Register your app ​

Step 2 — Redirect the user to Visuary ​

Step 3 — Exchange the code for an access token ​

Revoking access ​

Rotating the client secret ​