ambleloftEnterprise authentication API
Connect to a business API through host-managed sessions while keeping access tokens out of pages and model context.
Browse contracts, signatures, fields and examples. Unspecified defaults are not inferred.
On this page
01Declare a business resource
Add authentication at the manifest top level. These are placeholder addresses: replace them with your resource service and audience. baseUrl requires HTTPS and a trailing slash, without credentials, query or fragment.
"authentication": {
"resources": [{
"id": "business",
"title": "Business service",
"baseUrl": "https://api.example.com/v1/",
"audience": "https://api.example.com/",
"scopes": ["tasks.read"]
}]
}02Configure the IdP and sign in
Configure an OAuth Code + PKCE S256 public desktop client allowing http://127.0.0.1:{port}/callback. Set issuer/clientId in account settings. A page operation signs in through invocation.authentication.requestSession(resourceId); declare timeoutMs: 120000 for that operation.
03ExtensionAuthentication
Use context.authentication in the backend. Sessions are opaque identity references without access tokens. There is no global account enumerator or refresh token support.
| Field / API | Contract |
|---|---|
| getSession(resourceId): Promise<AuthenticationSession|null> | Read an existing session silently. |
| disconnect(resourceId): Promise<void> | Disconnect the resource. |
| onDidChangeSessions(listener): Disposable | Session change event; add it to subscriptions. |
| request({sessionId,path,method?,body?}) | Returns Promise<{status,body,contentType}>, body is a string. |
04Request scope and limits
Paths stay under the resource baseUrl prefix: with /v1/, /tasks requests /v1/tasks. Methods: GET/POST/PUT/PATCH/DELETE/HEAD. Arbitrary URLs, headers, cookies and redirects are not supported. JSON request bodies are limited to 256 KiB, responses to 1 MiB, with a 30-second timeout. No automatic retry; 401 invalidates the session.
const session = await context.authentication.getSession('business');
if (!session) throw new Error('Sign in from the extension page first');
const response = await context.authentication.request({
sessionId: session.id, path: '/tasks', method: 'GET'
});
if (response.status !== 200) throw new Error('Business request failed');05Session fields and isolation
AuthenticationSession contains id, resourceId, connectionId, account:{id,name}, scopes:string[] and expiresAt:number. Sessions bind to the extension, package revision, resource and connection. Local messages are not account-scoped; design message ownership explicitly when accounts change.
Open the complete runnable sample