kaiva BRIDGE
Guides / Accounts

Act on behalf of your users

Your users connect their own accounts once. After that every call your agent makes goes upstream as that user, and you write no OAuth code.

A server holds one credential, so by default every call goes upstream as your workspace. That is right for internal tools and wrong for a product with customers: an agent working for customer A is indistinguishable from one working for customer B at the upstream API.

Per-user accounts change the identity behind the call. Each of your users grants access once, Bridge holds the token, refreshes it before it expires, and stops using it the moment they revoke.

Register your OAuth app

You register your own app with the provider, not one of ours. That means any provider speaking OAuth 2 works the day you add it, with no approval queue and nobody to wait for. Open the Accounts tab on your server and fill in six fields.

ProviderA label for your own reference, such as google or slack.
Client IDFrom the provider's console.
Client secretSealed on save and never shown again. Leaving it blank on a later edit keeps the one already stored.
Authorize URLWhere the user is sent to consent.
Token URLWhere Bridge exchanges the code for tokens.
ScopesWhat you are asking for. Ask for the least that works.

The Accounts tab shows the redirect URL to register with your provider before you save, because most providers will not issue a client ID without one.

How a user connects

You do not build the link. When your agent calls a tool for someone who has not connected, Bridge answers with an error carrying a link made for that person. Give it to them, then retry once they are done. The link lasts ten minutes.

tool result
{
  "error": "account_not_connected",
  "message": "This tool acts for the signed-in user, and they
              have not connected their Calendar account yet.",
  "connect_url": "https://api.kaiv.ai/api/bridge/connect/calendar-a91f?t=..."
}

Everyone who has connected appears on the Accounts tab, showing when they last used it, with a control to revoke.

How the tokens are handled

At restEncrypted with AES-256-GCM, the same sealing as every other upstream credential. Never returned to the console, never returned to an agent.
On the wirePKCE on every authorization, S256, as OAuth 2.1 requires.
Connect linksSigned, and only ever issued for a user Bridge has already authenticated. Nobody can mint one naming somebody else.
Missing accountsA call for a user who has not connected is refused. It never falls back to your workspace credential, so an action is never silently attributed to the wrong identity.
IsolationEach workspace's accounts are separated at the database row level.
RevokingStops Bridge using the token immediately. Revoking at the provider itself is done in the provider's own settings.