Developers

Guide

Build an OAuth integration

Register an integration app, sign people in with authorization code and PKCE, export the audit log with client credentials, rotate and revoke.

At the end of this guide you have an integration app registered in Volobox, and either a tool that signs people in and calls the API as each of them, or a service that exports the organization audit log with a client secret. Registering the app needs the Manage API and MCP clients and webhooks permission; once it exists, any member can sign in through it.

Before you begin

  • The Manage API and MCP clients and webhooks permission in your workspace.
  • For an app people sign in through: the address your app receives the sign-in on (its redirect URI).
  • For a service: a secret store for the client secret, such as your CI system's or your cloud's.
  • curl to follow the examples; the last example also uses jq.

Choose what the app is

People sign in through itA service, with the client secret
Acts asThe person who signs inThe app itself, nobody behind it
FlowAuthorization code with PKCEClient credentials, or the secret as a bearer
ReachesThe app's groups, within what each person ticks on the consent page and can openAudit log only
Typical useAn external agent, a company tool, a command-line toolA SIEM or collector that exports audit events

Register the app

  1. In Volobox, open Admin at the bottom of the left activity rail, then Settings, and open API & MCP. Choose API or MCP: the apps are the same list.
  2. Click Create client and enter a name. People see it on the consent page.
  3. Under How it connects, choose People sign in through it or A service, with the client secret.
  4. Select the action groups. Each group says whom it works for: As the person who signs in, or for Audit log, Also with the client secret. A service is offered only the groups marked Also with the client secret.
  5. For People sign in through it, enter the Redirect URIs (see the rules below). Turn on Public client (no secret) for a command-line tool or desktop agent that cannot keep a secret: it signs people in with PKCE alone.
  6. Create the client, then copy the client id and, for a confidential app, the client secret (vbox_...).

Warning: The secret is shown once

Copy the client secret before you close the dialog. It is not shown again, and it does not expire on its own: it works until you rotate it or revoke the app. Keep it in a secret store, never in source control.

The Create client dialog in Organization Settings, API & MCP: a client name, how it connects (people sign in through it, or a service with the client secret), a redirect URI, the public client switch and the action groups it may use.
The Create client dialog in Organization Settings, API & MCP: a name, how it connects, the redirect URIs, the public client switch and the action groups.

Redirect URI rules

RuleDetail
AddressAn absolute https:// address, or http://localhost... or http://127.0.0.1... for a tool on the person's own machine.
Loopback portsOn a loopback address the port is not compared, so a local tool may listen on any port. One line such as http://127.0.0.1/callback is enough.
Own schemesAn app's own scheme, such as myagent://callback, is not accepted.
CountAt most 10 per app.
MatchThe redirect_uri your app sends must be one of the app's Redirect URIs exactly.

Sign people in with the authorization code flow

Before each sign-in, make a PKCE pair and a state value. The code challenge is the base64url SHA-256 of the verifier, without padding:

import crypto from "node:crypto";

const codeVerifier = crypto.randomBytes(32).toString("base64url");
const codeChallenge = crypto.createHash("sha256").update(codeVerifier).digest("base64url");
const state = crypto.randomBytes(16).toString("base64url");
  1. Send the person's browser to the authorization endpoint, with your values URL-encoded:

    Text
    https://volobox.example.com/connect/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=Volobox%20offline_access&code_challenge=CODE_CHALLENGE&code_challenge_method=S256&state=STATE

    scope=Volobox is required; offline_access adds a refresh token. PKCE with S256 is required.

  2. The person signs in to Volobox (with two-factor authentication, the code is asked on the same page) and sees a consent page that names your app and lists its action groups as checkboxes, every one ticked the first time. A group the person unticks stays out of your app's reach as them.

  3. Volobox sends the browser back to your redirect URI with code and state. Check that state is the value you sent.

  4. Trade the code for tokens at the token endpoint. A confidential app also sends client_secret; a public client does not:

    Bash
    curl -s -X POST 'https://volobox.example.com/connect/token' \
      -H 'content-type: application/x-www-form-urlencoded' \
      -d 'grant_type=authorization_code&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=CODE&code_verifier=CODE_VERIFIER'      --data-urlencode 'redirect_uri=REDIRECT_URI'

    The answer is a standard OAuth token response:

    JSON
    {
      "access_token": "ACCESS_TOKEN",
      "token_type": "Bearer",
      "expires_in": 3600,
      "refresh_token": "REFRESH_TOKEN",
      "scope": "Volobox offline_access"
    }
  5. Call the API with the access token as a bearer. The call acts as the person, within the groups they left ticked and what they can open:

    Bash
    curl -s https://volobox.example.com/api/v1/app-user/my-profile \
      -H 'Authorization: Bearer ACCESS_TOKEN'
  6. The access token lasts one hour. Before it runs out, trade the refresh token for a new pair, and store the new refresh token in place of the old one. A public client leaves out client_secret:

    Bash
    curl -s -X POST 'https://volobox.example.com/connect/token' \
      -H 'content-type: application/x-www-form-urlencoded' \
      -d 'grant_type=refresh_token&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&refresh_token=REFRESH_TOKEN'

The consent page is shown once per app. To let a person change their choice, send them to sign in again with prompt=consent added to the authorization URL; the boxes open as they last left them. A narrower choice reaches a token your app already holds when that token is renewed, within an hour.

Note

Never ask for a person's password in your app, and do not use a password grant. With two-factor authentication on, a password alone is refused. The authorization code flow handles two-factor authentication on Volobox's own page.

Export the audit log with client credentials

A service app with Audit log exports the organization audit log as JSON lines.

  1. Request an access token with the client id and secret. Without scope=Volobox the token is issued but every call answers 401:

    Bash
    curl -s -X POST 'https://volobox.example.com/connect/token' \
      -H 'content-type: application/x-www-form-urlencoded' \
      -d 'grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&scope=Volobox'

    The token lasts one hour; request another when it expires. The secret itself also works directly as a bearer.

  2. Read the export one page at a time from GET /api/v1/audit-log/export/jsonl. The body is NDJSON (application/x-ndjson), one JSON object per line. PageSize defaults to 500 and is at most 1000. The X-Volobox-Next-Cursor response header carries the next page's cursor: send it back as Cursor with the same filters, until the header is absent.

    Bash
    # Read these from your secret store.
    export CLIENT_ID="CLIENT_ID" CLIENT_SECRET="CLIENT_SECRET"
    
    TOKEN=$(curl -s -X POST 'https://volobox.example.com/connect/token' \
      -H 'content-type: application/x-www-form-urlencoded' \
      -d "grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&scope=Volobox" \
      | jq -r .access_token)
    
    CURSOR=
    while true; do
      ARGS=(--data-urlencode "FromUtc=2026-11-01T00:00:00Z" --data-urlencode "PageSize=500")
      [ -n "$CURSOR" ] && ARGS+=(--data-urlencode "Cursor=$CURSOR")
      curl -s -G -D headers.txt -H "Authorization: Bearer $TOKEN" "${ARGS[@]}" \
        'https://volobox.example.com/api/v1/audit-log/export/jsonl' >> audit.jsonl
      CURSOR=$(grep -i '^X-Volobox-Next-Cursor:' headers.txt | awk '{print $2}' | tr -d '\r')
      [ -z "$CURSOR" ] && break
    done

The other filters (ToUtc, Categories, EventKeyPrefix, ActorFilter and more) are in the Audit log API.

Rotate and revoke

On the app's row in API & MCP:

  • Edit changes the name, the groups, How it connects and the redirect URIs.
  • Rotate secret in the ⋯ menu replaces the secret and ends every token the app was issued. Put the new secret in your secret store before your service's next token request.
  • Revoke in the ⋯ menu stops the app at once: its secret, every token issued through it, and every person's sign-in through it. An old token is refused with 401 everywhere.
  • Delete in the ⋯ menu removes a revoked app's row, together with every person's consent to it. An active app cannot be deleted, only revoked.

Some edits also end the app's issued tokens, and people sign in again and see the consent page: switching a sign-in app to a service, switching between public and confidential, and adding a group. Taking a group away needs no new sign-in: the next call no longer reaches it.

Check that it works

  • For a sign-in app, the my-profile call with the access token returns the profile of the person who signed in.
  • For a service, the export loop writes lines of audit events to audit.jsonl.
  • The app's row shows its kind: Sign-in, Secret, or Sign-in and secret.
The integration clients on API & MCP: a sign-in app with its redirect URI and action groups, and a service limited to the Audit log, each with Edit.

Troubleshooting

SymptomFix
The sign-in fails with "redirect_uri is not valid"The address your app sent is not one of the app's Redirect URIs. Add it exactly.
Every call with a client credentials token answers 401The token request left out scope=Volobox. Request a new token with it.
A call with the secret answers 403 with Volobox:Integrations:MemberConnectionRequiredThe action acts as a person: a group other than Audit log, or an action about the signed-in person. Sign the person in through the app, or have them use a personal token.
A call answers 403 with Volobox:Integrations:ActionNotGrantedThe action is outside what the bearer reaches: not in the app's groups, unticked by the person, or a permission the person lacks.
An old token answers 401 after you rotated or revokedExpected: rotating and revoking end every issued token. Get a new one.
Creating the app says the OAuth application limit is reachedDelete an unused OAuth application or revoke an app. Plan limits are on Pricing.
You need a grant other than authorization code or client credentialsUse Organization Settings > OAuth. Apps created there do not appear on API & MCP.

Next steps