Skip to main content
The Workspace API authenticates with an organization-owned credential that begins vq_ws_.

​
Creating a credential

1

Open the automation console

Sign in to Vaquill and go to Automation in the sidebar. You must be an owner of the organization; members cannot provision API access.
2

Enable the Workspace API

This creates an installation owned by your organization, not by you personally. It keeps working if you later leave the organization.
3

Create a credential

Give it a name that says what will use it, for example billing-sync or intake-bot. Choose an expiry.
The credential is shown once and is never retrievable. There is no reveal endpoint, deliberately: this credential reaches privileged client material. Store it in your secrets manager before closing the dialog.
Everything your integration does afterwards is headless. Managing credentials is not: listing, issuing and revoking all run through the console and need a signed-in organization owner, and a vq_ws_ credential cannot call them. That is deliberate. A credential that could mint credentials would make revoking one meaningless. There is no rotate operation. Rotating means issuing a second credential, deploying it, then revoking the first, which is the same sequence with none of the ambiguity about which one is live.

​
Credential properties

The last six characters are a checksum, so a truncated or mistyped credential is rejected before it reaches our database. If you get invalid-credential immediately on a key you just pasted, check for a copy that cut off the end.

​
Scopes

A credential carries scopes in the form resource:action. Write implies read on the same resource; run does not, so a reporting integration can be given read access without the ability to start billable work.
Most integrations want far less than this. A good default is the narrowest set that makes your first call work, widened when a 403 tells you exactly what is missing.
The scope vocabulary is slightly wider than the list above, because it was frozen before every capability shipped. A few names are accepted but govern no endpoint yet. Granting one is harmless and grants nothing, so build against the list above.
Folders have no scope of their own. They are governed by matters:read and matters:write, because a folder is an organizing device for matter work rather than a resource in its own right.
documents:download is separate from documents:read on purpose. Listing document metadata and pulling an original confidential file are different risks, so an integration that only checks ingestion status need not be able to retrieve originals.
A request missing a required scope gets 403 with an insufficient-scope problem document naming the scopes it needed.

​
Attributing actions to a person

If the work your integration does is initiated by one of your users, send their identifier:
It is accepted on every operation, including over MCP, where it is set once on the connection. You will not find it in the generated reference: it is read by a layer that sits in front of the routes, so no individual operation declares it. This page is its documentation. It is recorded on the audit trail for that action, verbatim. It is optional, and when it is absent the action is recorded as an autonomous service, which is the honest description of a job nobody in particular asked for. Any identifier works: an email, a directory DN, your own user id. Surrounding whitespace is trimmed and the rest is stored exactly as sent, which is why there are two rules: at most 200 characters, and no control characters. A value breaking either is refused with 400 acting-user-rejected rather than repaired, because a shortened or scrubbed identifier is a different identifier presented as your assertion.
This value is asserted by your system and not authenticated by us. We record it as your assertion and never present it as a verified Vaquill identity, and we do not check it against your organization’s members. If your firm needs cryptographic attribution of a named person for an ethical wall, talk to us before relying on this.

​
Revoking

Revoke from the automation console or with DELETE /api/v1/workspace/credentials/{credentialId}. Revocation takes effect immediately, including for requests already in flight against a cached credential.
Last modified on August 19, 2026