Connect with Dib

“Connect with Dib” is a hosted handoff for partners who want a one-click way to get a scoped API key for an existing Dib home. You send the user to a Dib-hosted consent screen, they approve the access you asked for, and we hand your app back a live key. No OAuth dance to build on your side.

This is the flip side of the Partner Provisioning API: provisioning creates a brand-new home for someone, while Connect asks an existing Dib user to grant you access to theirs.

The flow at a glance

1. You build a Connect link with your partner slug, the target team, the scopes you need, and your redirect_uri.
2. The user lands on the consent screen at /developers/connect. They see who's asking and exactly what they're granting.
3. They tap “Allow access”. Dib mints a scoped key on the team's behalf.
4. We redirect back to you with ?dib_key=…&state=… appended to your redirect_uri.

1. Build the Connect link

Point the user at https://dib.io/developers/connect with these query params:

• partner— your partner slug (assigned by the Dib team).
• team — the Dib team_id you want to connect. The user must be signed in to Dib and an owner of this team.
• scopes— comma-separated scopes you're requesting (for example inventory:read,documents:read).
• redirect_uri— where we send the user afterward. This must be allowlisted on your partner record, or the screen returns an error.
• state— optional opaque value we echo back so you can tie the callback to the request and guard against CSRF.

const url = new URL("https://dib.io/developers/connect");
url.searchParams.set("partner", "acme");          // your partner slug
url.searchParams.set("team", teamId);              // the Dib team to connect
url.searchParams.set("scopes", "inventory:read,documents:read");
url.searchParams.set("redirect_uri", "https://acme.example.com/dib/callback");
url.searchParams.set("state", state);              // opaque, echoed back to you

// Send the user here (full-page redirect or popup)
window.location.href = url.toString();

2. What the user sees

The consent screen shows your name, logo, and description alongside the access you're asking for. We only ever show the user scopes that are both in your request andon your partner record's allowlist — anything you request beyond that is quietly dropped and called out so the user knows it wasn't granted.

Granting a partner key is a Pro feature, and the team needs the Public API enabled. If either isn't true, the user sees a clear prompt instead of a dead end. We also require a fresh re-authentication (password or passkey) before minting, so a stray tab can't hand out a key.

3. Handle the callback

After the user approves, we redirect to your redirect_uri with a live key in dib_key and your original state:

https://acme.example.com/dib/callback?dib_key=dib_live_abc...xyz&state=OPAQUE_STATE

The key is named after you (“Acme (Connect)”), scoped to exactly what was granted, and tied to the user's team. Store it server-side and use it as a normal Bearer token against /v1. Call GET /v1/me first to confirm the scopes and team you ended up with.

Good to know

• The user can revoke your access anytime from their Dib settings, after which the key starts returning 401.
• stateis echoed verbatim — always verify it matches what you sent before trusting the callback.
• Treat dib_keylike a password. It only appears once, in the callback URL — never log it or expose it client-side.
• Need a partner slug or a redirect_uri added to your allowlist? Email developers@dib.io.