Credential Hand-off

Embedded integrations invert the usual OAuth flow. Your customer authorizes Slack, GitHub, or any other provider inside your product, against your OAuth app. Your backend then pushes the resulting tokens into the customer's workspace, where agents pick them up on their next run. Levain stores the tokens encrypted and ships them only into that workspace's sandboxed runs.

Push a credential

curl -X PUT "https://api.levainlabs.com/api/v1/org/workspaces/$WS_ID/integrations/github" \
  -H "Authorization: Bearer $LEVAIN_ORG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "oauth2",
    "external_account_id": "acme-tools",
    "display_name": "Acme Tools GitHub",
    "credentials": [
      {
        "type": "oauth_access",
        "payload": {"access_token": "gho_..."},
        "expires_at": "2026-08-26T18:00:00Z"
      }
    ]
  }'

PUT is create-or-rotate: the same call with a fresh token replaces the old one. external_account_id is your identifier for the connected account, so one workspace can hold several accounts of the same provider.

The expiry contract

Levain never refreshes a pushed token — refresh tokens and OAuth client secrets stay with the owner of the OAuth app, which is you. That makes expiry your side of the contract:

• oauth_access credentials must carry expires_at; the API refuses them without it.
• Push a fresh token before that moment, on whatever schedule your token lifetimes demand.
• If an agent run finds a credential no longer works, the credential.revoked webhook event fires so you can re-authorize the customer promptly.

Long-lived credentials — personal access tokens (pat), bot tokens, static headers — can be pushed without expires_at and rotated whenever you choose.

Check health

GET /api/v1/org/workspaces/{workspace_id}/integrations lists each integration with per-credential health derived from stored expiry times. Secret material is never returned; you get expires_at and an expired flag, which is enough to drive a re-push job or a "reconnect" prompt in your product.

Revoke

When a customer disconnects an account, delete the integration:

curl -X DELETE "https://api.levainlabs.com/api/v1/org/workspaces/$WS_ID/integrations/$INTEGRATION_ID" \
  -H "Authorization: Bearer $LEVAIN_ORG_KEY"

Stored credential material is deleted immediately; the integration record is kept, marked revoked, so your audit trail stays intact.