AuthKit

AuthKit is AgentOS's OAuth-style authorization service for third-party apps.
It allows apps to securely obtain AgentOS user identity without dealing with the underlying account system directly.

What it solves

AuthKit handles:

• Third-party apps requesting authorization from AgentOS users
• Users confirming authorization on the AgentOS desktop
• Auth code exchange for access tokens
• Retrieving user info (userId, name, avatarUrl) via access tokens
• Grant revocation and lifecycle management

Best fit

• Your app needs to identify the current AgentOS user
• You need to associate the same user across multiple devices
• You need user identity in DiscoveryKit or TransferKit to identify "who sent the file"
• You need user-scoped data isolation

Authorization flow

AuthKit uses a pattern similar to the OAuth authorization code flow:

1. App calls POST /authkit/authorize with the AppKit bearer token
2. If previously authorized, returns authCode immediately (status=granted)
3. If first time, returns requestId (status=pending), waiting for user approval
4. App polls GET /authkit/authorize/<requestId>/status until status becomes granted
5. With authCode, call POST /authkit/token to exchange for accessToken
6. Use accessToken to call GET /authkit/userinfo for user details

Core capabilities

Initiate authorization

Common entry points:

• SDK (TypeScript): sdk.authkit.authorize(bearerToken, { scopes: ['profile'], appName: 'MyApp' })
• SDK (Python): await sdk.authkit.authorize(bearer_token, {"scopes": ["profile"], "appName": "MyApp"})
• HTTP: POST /authkit/authorize

Poll authorization status

• SDK: sdk.authkit.getStatus(bearerToken, requestId)
• HTTP: GET /authkit/authorize/<requestId>/status

Possible status values: pending, granted, denied, timeout

Exchange token

• SDK: sdk.authkit.exchangeToken(bearerToken, { authCode })
• HTTP: POST /authkit/token

On success returns:

• accessToken: used for subsequent user info requests
• userInfo: contains name and avatarUrl
• userId: unique per-app user identifier (hash of login ID + bundleId)

Get user info

• SDK: sdk.authkit.getUserInfo(accessToken)
• HTTP: GET /authkit/userinfo (with accessToken as Bearer token)

Revoke authorization

• SDK: sdk.authkit.revoke(bearerToken)
• HTTP: POST /authkit/revoke

Relationship with AgentOS login state

AuthKit access token validity follows the AgentOS login state:

• User logs out → all app tokens invalidated, apps receive logout event
• Account switch → all grants and tokens cleared, apps receive account_switch event
• Same account re-login → grants preserved, apps receive login event

When you may not need AuthKit

• Your app does not need to know who the current user is
• You only use ModelKit for model calls without involving user identity
• You do not need cross-device user association

Next steps

• For device discovery and pairing: see DiscoveryKit
• For cross-device file transfer: see TransferKit
• For app registration and basic token: see AppKit