Capability: integration.auth
The integration.auth capability enables a consent flow for narrowly scoped local integration access. Credentials are returned only when required by the approved scope.
When is it available?
integration.auth appears in the welcome capabilities when the user is signed in and at least one integration authorization surface is available.
If it is missing, your client should fall back or retry later.
Request flow
- Send
hellowithclientType: "integration". - Send
request_accesswithclientId,displayName, andrequestedScopes. - The user sees a consent modal in the dashboard app.
- You receive either
access_grantedoraccess_denied.
See the full message schemas in Message Reference.
Scopes
| Scope | Purpose | Returned credential |
|---|---|---|
rest.full | Use the account REST API | Channel API key |
avatar.events.read | Subscribe to avatar animation state and optional TTS audio | Opaque reconnect credential |
vision.rtmp.configure | Configure the legacy Vision publishing output | Vision RTMP credential |
vision.installation.register | Link a managed Vision installation | Installation authorization |
Request only the scopes your integration needs.
Responses
Success:
{
"type": "access_granted",
"payload": {
"requestId": "req_01HZXN5A",
"apiKey": "sk_live_xxxxx",
"scopes": ["rest.full"],
"channelName": "mychannel"
}
}Avatar-only success:
{
"type": "access_granted",
"payload": {
"requestId": "req_01HZXN5A",
"scopes": ["avatar.events.read"],
"reconnectCredential": "aig_opaque_credential"
}
}The reconnect credential is bound to the current ai_licia account, Desktop installation, and integration clientId. Desktop persists only a credential hash. The integration must store its opaque credential and supply it in a later hello. Users can revoke avatar grants from the Desktop Integrations page.
Denial:
{
"type": "access_denied",
"payload": {
"requestId": "req_01HZXN5A",
"reason": "user_denied"
}
}Possible reason values:
user_deniedtimeoutnot_ready
Error codes
Errors are sent with type: "error" and a typed code:
missing_helloinvalid_client_typeinvalid_client_idinvalid_scopenot_readyrequest_pendingrate_limitedui_unavailable
Rate limits and timeouts
- One pending request per
clientId. - Requests within a short cooldown window are rejected (
rate_limited). - Pending requests expire automatically after a short timeout.
Revocation
REST access is revoked by regenerating the channel API key. Avatar grants are revoked individually from Desktop. Revoking an avatar grant closes its active socket and invalidates its reconnect credential. Changing ai_licia accounts also invalidates the previous account’s avatar grants.