Skip to Content
Build with FinquApps & IntegrationsAdmin Context

App Context

This page describes how Finqu Admin authenticates embedded app requests using Finqu App Context. When your app is opened inside Finqu Admin (for example as an embedded view), the context token tells your app which merchant the request is for.

OAuth flows, access tokens, and scopes are documented in App Installation & Authentication and the Authentication guide. This page focuses only on the context token used for embedded requests.

What is App Context

When Finqu Admin opens your app (typically as an embedded view), it provides a context token with each request:

  • The token is a JWT signed by Finqu (using your app’s client secret on Finqu’s side).
  • You validate it using your client secret — the same credential you use for OAuth token exchange. There is no separate app token; the context token JWT is signed with the client secret.
  • The token identifies the merchant via the JWT sub claim, formatted as merchant/{id}.

Receiving the context token

Finqu Admin and embedded tooling may send the context token in any of the following ways. Your app should accept it from all three so that it works in every situation:

  1. Query string: token
  2. Request body: token (form or JSON)
  3. HTTP header: Finqu-Context

Validating the context token (backend)

Your server must verify the context token before trusting the request. Implement an app-context guard that runs on every endpoint called from Finqu Admin.

What the guard should do

  • Read the context token from the token parameter/field or the Finqu-Context header.
  • Verify and decode the JWT using your app’s client secret.
  • Extract the merchant identifier from the JWT sub claim (format: merchant/{id}).
  • Attach the merchant id to the request context for your handlers.
  • Return 401 Unauthorized if the token is missing or invalid.

Admin URL

The merchant’s Finqu Admin base URL must be fetched from the OAuth resource endpoint only (during or after the install flow) and stored per installation. Use that stored Admin URL whenever your embedded bridge or frontend needs the Admin origin—for example when initializing App Link with the correct origin.

Where to apply the guard

Apply the app-context guard to every endpoint that is called from Finqu Admin embedded views—including pages, dialog content, and API endpoints your frontend calls. If an endpoint needs to know the merchant, it must require a valid context token.

Sending the context token from the frontend

When your app runs inside Finqu Admin, the browser does not create the context token. It receives it from the embedding layer (for example via a bridge configuration in the server-rendered HTML, such as app id and Admin origin). A bridge library then provides a way to get the current context token for the active merchant session.

Your frontend must send that token to your backend on every request. You can use any of these patterns; choose one and use it consistently, but keep your backend able to accept all three:

  1. Header: Finqu-Context: <token>
  2. Request body: include a token field (for JSON or form posts)
  3. Query string: ?token=<token> (for nested pages or iframes, for example in dialogs)