---
title: "Mint an embedded-surface session (human session only)"
method: POST
path: "/v1/apps/{id}/session"
tags: ["Apps"]
---

# Mint an embedded-surface session (human session only)

`POST /v1/apps/{id}/session`

## Request

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

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.

## Path parameters

- `id` string, uuid, required

## Response `201`

Session issued.

- AppSurfaceSession: A short-lived OAuth access token a workspace shell hands to an app's embedded surface (docs/APPS-SPEC.md). No refresh token is issued: the shell calls the route again to renew.
  - `access_token` string: 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_in` integer: Lifetime in seconds (apps.embedded_session_ttl_seconds).
  - `expires_at` string, date-time
  - `scopes` string[]: 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_id` string, uuid
  - `app_id` string, uuid
  - `api_base` string: Absolute API origin the surface calls back into (API_URL, else this request origin).
  - `surface_url` string, nullable: The install's surface URL - what the shell frames.
  - `allowed_origin` string, 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.

## Other responses

- `403`: The API key does not have the required scope.
- `404`: The requested resource was not found.
- `409`: The request conflicts with the current resource state.

---

[API](https://skmtc.dev/talonic/apis/talonic-api.md) · [All operations](https://skmtc.dev/talonic/apis/talonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/talonic/apis/talonic-api/revisions/678fe5f8c9c3?raw)