Build Spaces into whatever you’re making.

Many wonderful ways to use it

It starts with one token

Mint a scoped Personal Access Token in your workspace settings, grant it only what it needs — read files, write files, search — and call the API. Tokens carry exactly the access you give them and never more than the person who made them already has.

# List everything in an Area
curl https://your-workspace.vidualspaces.com/api/v1/files?area=brand \
  -H "Authorization: Bearer vsk_your_token_here"

# Get a short-lived download link for one file
curl "https://your-workspace.vidualspaces.com/api/v1/files/download\
?area=brand&key=logos/wordmark.svg&filename=wordmark.svg" \
  -H "Authorization: Bearer vsk_your_token_here"

Scopes: files:read, files:write, areas:read, shares:write, search:read, and more. Everything is versioned under /api/v1, so what you build today keeps working.

Or reach for the SDK

If you’re working in TypeScript or Node, the official SDK wraps all of this — tokens, uploads (it picks single-PUT or multipart for you), areas, shares, search, OAuth and webhooks — behind a handful of typed calls, so you can skip the plumbing and get straight to the part you wanted to build.

npm install @vidual/spaces

import { SpacesClient } from "@vidual/spaces";

const spaces = new SpacesClient({
  baseUrl: "https://your-workspace.vidualspaces.com",
  accessToken: process.env.SPACES_TOKEN, // vsk_…
});

// See where you can write, then push a file.
const areas = await spaces.areas.list();
await spaces.files.upload({
  area: "brand",
  key: "logos/wordmark.svg",
  data: bytes,
  contentType: "image/svg+xml",
});

Zero runtime dependencies, ships its own types, Node 18+. Read the full surface — OAuth, webhooks and Vidual Send included — on npmjs.com/package/@vidual/spaces.

Building something other people will use?

A Personal Access Token is the right tool when you’re building for yourself. When you’re building a product — something your own users will connect their Spaces workspace to — register it as an OAuth app from your workspace settings and you’ll have a client id and secret in about a minute. Your users approve exactly the scopes you ask for on a consent screen, access tokens refresh quietly in the background, and a single registration works for users on any Spaces workspace. Under the hood it’s OAuth 2.1 with PKCE — the same modern flow your framework already speaks — and the SDK handles the whole dance if you’d rather it did.

One thing worth knowing before you start: every workspace lives on its own subdomain, and both the OAuth endpoints and the API live there with it. Your app is registered once, globally, but each user authorises — and you then act — on theirworkspace’s host, so your connect flow starts by asking which workspace they’re bringing.

# 1. Send the user to their workspace's consent screen (PKCE S256 required)
https://their-workspace.vidualspaces.com/oauth/authorize
  ?client_id=vsa_your_client_id&redirect_uri=https://your.app/callback
  &scope=files:read+search:read&state=…&code_challenge=…&code_challenge_method=S256

# 2. They come back with a code — exchange it on the same host
curl https://their-workspace.vidualspaces.com/oauth/token \
  -d grant_type=authorization_code -d code=… -d code_verifier=… \
  -d client_id=vsa_your_client_id -d client_secret=vsc_your_secret \
  -d redirect_uri=https://your.app/callback

# 3. Call the API on that workspace with the access token you're given
curl https://their-workspace.vidualspaces.com/api/v1/files?area=brand \
  -H "Authorization: Bearer vso_the_access_token"

Each credential wears its name: vsa_ client id, vsc_ client secret, vso_ access token, vsr_ refresh token — and vsk_ stays the Personal Access Token from above. Only vso_ and vsk_ go in a Bearer header. Every workspace host also serves /.well-known/oauth-authorization-server if your OAuth library prefers to discover all this itself.

What about Vidual Send?

Send is a slightly different animal — quick, accountless, here-then-gone transfers, not a permanent home — so it gets its own small, key-based API instead of riding on a person’s Spaces login. The plan: fire off a Send transfer straight from your app, and let a recipient save what they’ve been sent into a Spaces Area in a click. The ephemeral front door and the permanent home, wired together. That one’s on the roadmap, not live yet — tell us if you’d use it and we’ll move it up.

Built with Spaces

We’re just opening the doors, so this wall is waiting for its first builds. If you make something with the API — a portal, an automation, a daft little side project — we’d love to see it. We’ll feature the ones we love right here, send people your way, and generally make a fuss. Consider it a standing invitation to show off.