Overview

The demo is a small, unbranded PHP app that a partner drops into their own site. Everything runs server-side: the browser never sees a token. The whole integration is four steps.

1

Connect

Send the user to BentBox's consent screen with your client_id, requested scopes, and a CSRF state.

2

Approve

The user signs in to BentBox and approves. BentBox redirects back to your redirect_uri with a short-lived code.

3

Exchange

Your server swaps the code plus your client_secret for an access_token and connection_id, and stores them encrypted.

4

Upload

Create video metadata, request a presigned URL, and upload the file bytes.

Phase A · Connecting an account

The OAuth handshake. Steps 1–5 are browser redirects; the sensitive exchange in step 6 happens server-to-server, so your client_secret is never exposed.

Sequence · OAuth authorization code flow
User's BrowserYour ServerBentBox APIGET /connect.php1302 → /oauth/authorize2sign in + approve3302 → /callback.php?code4GET /callback.php?code5POST /oauth/token6access_token + connection_id7Set bb_conn cookie (encrypted)8

GET connect.php kicks it off and GET callback.php receives the return; the token exchange is a POST to /oauth/token.

⚠ redirect_uri must match exactly

The redirect_uri you send must be registered on your BentBox account character-for-character — same scheme, host, and path, no trailing slash. A mismatch returns invalid_client.

Phase B · Uploading a video

With the stored token, uploading is two API calls plus the file transfer. The token rides in both the request body and an Authorization: Bearer header.

Sequence · Content upload
User's BrowserYour ServerBentBox APIPOST ?action=prepare1POST /v1/content/video2video_id3POST /v1/content/upload-url4presigned URL5presigned URL6PUT file → presigned storage7

POST /v1/content/video reserves a video_id, POST /v1/content/upload-url returns a presigned URL, and a PUT sends the bytes. In proxy mode the PUT runs on your server instead of the browser.

The create call also carries the consent attestation — either sole_performer: true or a ProntoID release_form_id covering additional performer(s) — and an optional publish_on_ready flag (default true) that controls whether BentBox makes the video live once processing and approval complete.

The files

Nine files, no dependencies. Download individually below, or grab everything at once.

Whole package — ready to drop into your web root.

↓ Download all (.zip)
config.phpsetup
Your settings: credentials, redirect URI, scopes, cookie key.
↓ Download
bentbox.phpcore
The library: HTTP, OAuth, encrypted-cookie token store, upload calls.
↓ Download
partials.phpui
Shared, unbranded page chrome and CSS.
↓ Download
index.phpoverview
Landing page: explains the flow, shows connection status.
↓ Download
connect.phpstep 1
Starts OAuth: sets the state cookie, redirects to BentBox.
↓ Download
callback.phpsteps 2–3
Redirect target: verifies state, exchanges the code, stores tokens.
↓ Download
upload.phpstep 4
Upload UI + server actions (create → sign → PUT).
↓ Download
README.mddocs
Full setup walkthrough and API reference.
↓ Download
flow.phpdocs
This page.
↓ Download

Setup

1

Copy the folder into your web root

Serve it over HTTPS — OAuth and secure cookies require it.

2

Register your redirect URI

Add the exact URL of callback.php to your BentBox redirect_uris.

3

Generate a cookie key

Use the same value on every server.

4

Fill in config.php

Credentials, redirect URI, scopes, and the key — then open index.php.

# generate the 32-byte cookie key
php -r "echo base64_encode(random_bytes(32)).PHP_EOL;"

🔑 One key, every instance

The cookie key encrypts the stored tokens. Behind a load balancer, all nodes must share the identical key, or a connection written by one node won't decrypt on another.