Apps

Mint an embedded-surface session (human session only)

Issues the access token a workspace shell hands to this app's embedded surface: the app's declared surface.scopes, the caller's workspace role as the token's role claim, a lifetime of minutes and NO refresh token. Machine callers are 403; 409 when the workspace holds no installed app with a bound OAuth client, or the app has no published version. The Apps guard caps such a token at min(scope tier, role tier), so it can never outrank the person who opened it.

post/v1/apps/{id}/session

Request

Base URL: https://api.talonic.com
URL: https://api.talonic.com/v1/apps/{id}/session
Auth: HTTP bearer

Path parameters

idstring uuid required

Response

Session issued.

access_tokenstring

OAuth 2.1 access token, aud talonic:public-api. Its claims carry the same role and tier reported below, so a surface reached through the redirect flow reads the tier off the token itself.

token_type'Bearer'

expires_ininteger

Lifetime in seconds (apps.embedded_session_ttl_seconds).

expires_atstring date-time

scopesstring[]

The app's declared surface.scopes, narrowed to the pre-consentable set.

role'viewer' | 'member' | 'senior_member' | 'owner'

The caller's client role in the workspace, carried on the token as the role claim.

tier'read' | 'run' | 'operate' | 'configure'

The Apps tier this token actually reaches: min(scope tier, role tier). A surface hides controls above it rather than discovering the 403.

workspace_idstring uuid

app_idstring uuid

api_basestring

Absolute API origin the surface calls back into (API_URL, else this request origin).

surface_urlstring nullable

The install's surface URL - what the shell frames.

allowed_originstring nullable

The install's one allowed browser origin: the shell's postMessage target and the only origin it accepts messages from. Carried here because the install row itself is readable only by an owner, and any member may open a surface.

Changes

No recorded changes to this operation across all 1 revision of this API.