Apps

Install an external app (human workspace owner only)

Mints the service key carrying the decide grant plus the manifest's required_grants, stores the surface URL and allowed browser origin, and pre-consents the OAuth client. The plaintext key is returned ONCE and is never retrievable again. Machine callers are 403 whatever grants they hold.

post/v1/apps/{id}/install

Request

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

Path parameters

idstring uuid required

Request body

surface_urlstring

https URL of the external service UI; surfaces as endpoints.surface.

allowed_originstring

Exact https origin admitted for the surface's browser calls. Must match the host of one of the OAuth client's registered redirect URIs, so oauth_client_id is required with it.

oauth_client_idstring uuid
key_namestring
confirm_subscriptions_endpointstring

The manifest's subscriptions_endpoint, retyped by the owner (§B13.2 check 2). Required, and compared byte-for-byte, whenever the active version subscribes to anything.

bindingsobject

Requirement slots bound to workspace resources, { "<alias>": "<uuid>" | "self" } — one entry per non-optional, non-self-scope slot the manifest's requires[] declares (see AppManifest.requires).

Example request

{
  "bindings": {
    "invoices": "3f9c9e3a-1b2c-4d5e-8f60-1234567890ab"
  }
}

Response

Installed. The service key AND the subscription signing secret appear here and nowhere else.

service_keystring
masked_prefixstring
subscription_secretstring nullable

The signing secret every subscription row of the install shares; null when the manifest subscribes to nothing.

warningstring

Changes

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