> ## Content Index
> Fetch the complete content index at: https://blog.protokol.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# Web apps: sites people open from Protokol and sign in to
- URL: https://blog.protokol.io/web-apps/
- Published: 2026-11-17T17:33:06.000Z
- Updated: 2026-11-17T19:14:58.000Z
- Description: Create a web app that people open from their Protokol home screen and sign in to with their Protokol account, keep it private or publish it, and control what it can do.
- Author: Strahinja Djuric
- Tags: Engineering

A web app is a website or single-page app that people open from Protokol and sign in to with their Protokol account. You create it under **Developer → Web apps**, next to your other apps. It signs users in with Sign in with Protokol (OpenID Connect).

Web apps are not OAuth clients. OAuth clients are credentials for integrations that call the Protokol API: scripts, CLIs and servers. If you are building one of those, read the [OAuth 2.0 post](https://blog.protokol.io/oauth2/) instead. This post is about apps with a Launch URL that people open.

## Create a web app

Sign in to the dashboard as a project admin, open **Developer → Web apps**, and choose **Create web app**. The form asks for:

| Field                          | Description                                                                           |
| ------------------------------ | ------------------------------------------------------------------------------------- |
| Name, description, logo, links | Shown on the consent screen and, for public apps, in the marketplace                  |
| Launch URL                     | Where Protokol sends people who open your app                                         |
| Redirect URIs                  | Exact https:// callback URIs of your app                                              |
| Sign in                        | The profile and email details your app asks for                                       |
| API permissions                | Optional. Only needed if your app calls the Protokol API. Sign-in-only apps need none |
| Visibility                     | Private or Public                                                                     |

![The Create web app form filled in for Acme Portal with a launch URL and a redirect URI](https://blog.protokol.io/content/images/2026/11/01-create-web-app.png)  
*The Create web app form: name, launch URL and redirect URI.*

On save, a confidential app shows its client secret once. Copy it into your secret store; you can rotate it from the app's page. A web app is confidential by default, and a single-page app that cannot keep a secret can be created as a public client that uses PKCE.

## Private or public

|                | Private                                           | Public                                     |
| -------------- | ------------------------------------------------- | ------------------------------------------ |
| Who can use it | Members of your project                           | Members of any project that installs it    |
| Review         | None                                              | Protokol reviews it before it is listed    |
| Marketplace    | Never listed                                      | Listed after approval                      |
| Home screen    | Members of your project, once a Launch URL is set | Members of every project that installed it |
| Changes        | Apply immediately                                 | New revisions are reviewed                 |

For a public app, choose **Request publication**. Edits to the name, description, logo, homepage, terms of service, privacy policy, Launch URL and redirect URIs create a new revision. The marketplace keeps showing the approved version until the new one is approved, and an edit never removes your app from the marketplace. In your own project you see your changes immediately, so you can test them before review.

## The launch flow

The Launch URL must be `https`, with no fragment and no credentials, and its host must share a registrable domain with one of your redirect URIs. When someone opens your app, Protokol sends their browser a `GET` request:

```
GET https://app.example.com/start?iss=https://lemon.protokol.io&project_id=PROJECT_ID

```

`iss` and `project_id` are the only parameters Protokol adds. Your app then:

1. Checks that `iss` equals the issuer from the discovery document, and rejects the request otherwise.
2. Starts its normal OpenID Connect authorize request with a fresh `state`, `nonce` and PKCE challenge, forwarding `project_id`. The user is not asked to choose a project again.

Try `prompt=none` first. If the user already approved your app, they get straight in without a screen. On a `login_required` or `consent_required` error, send them through again without `prompt=none`. The Launch URL carries no code, so always complete the full authorization code flow.

## Installing in a project

For a public app, a project admin installs it from the marketplace before the project's members can sign in. A member who opens it from the marketplace card is told to ask an admin. Installed apps show under **Your apps** on every member's home page. Your own project does not need to install it.

If someone signs in from your own site to a project that does not have the app yet, an admin sees a consent screen noting that approving also installs the app. A member can only decline, which returns `access_denied`. With `prompt=none` the request returns `interaction_required`.

Admins manage installed apps under **Developer → Web apps → Installed from the marketplace**. If an admin uninstalls an app, access for every member of that project is revoked: access tokens stop working and refresh tokens are rejected.

### Workspace access

Admins choose which workspaces can use an app, at install time and later. By default every workspace has access. A member whose role is not linked to an allowed workspace cannot sign in to the app in that project, and the app does not appear on their home page. Project admins always have access. Narrowing the workspaces revokes the access of members who no longer qualify. This also applies to private apps.

## Permissions your app gets

If your app calls the Protokol API, the permissions in its access token come from three sources:

| Source                        | Who sets it                                   | Depends on the user's own rights?                                      |
| ----------------------------- | --------------------------------------------- | ---------------------------------------------------------------------- |
| What users approve at sign-in | The user, on the consent screen               | Yes. A user can only approve what they hold                            |
| Entitlements                  | You, the developer                            | No. Always granted                                                     |
| Grants from a project admin   | An admin of a project that installed your app | Regular grants: yes, and the user must approve them. Forced grants: no |

**Approved scopes.** Your app requests permissions in `scope`, up to the API permissions you allowed on the app. The token holds only what the user is allowed to do in that project.

**Entitlements.** You list permissions your app always needs on its page under **Developer → Web apps**. They are in every token whatever the member's role, and members do not approve them. They are literal permission names, with no patterns. For a public app they are part of the listing, so a change goes through review.

**Admin grants.** After installing an app from another project, an admin can add any permission of the project from the app's Settings. A regular grant is an offer, shown to each member who holds that permission as "New from your project admin"; it reaches the token only after they approve. A forced grant goes to every member who can use the app without asking, so admins should add one only when the app does the work on the project's behalf. Entitlements and forced grants appear on the consent screen under "Also granted".

Changes reach your app at its next token refresh or code exchange, so request `offline_access` if you need to pick them up without a new sign-in. Introspection returns `oauth_ungated`, the permissions granted regardless of the user's own rights:

```
{
  "active": true,
  "scope": "perm64:… perm64:…",
  "oauth_ungated": ["manage orders"]
}

```

Treat anything in `oauth_ungated` as something the app may do for anyone, and the rest as things this particular user may do.

## Signing users out when access ends

Your app keeps its own session, and it does not end by itself when Protokol access ends. Access ends when the user disconnects the app, an admin revokes or uninstalls it, an admin narrows workspace access, the app is suspended or deleted, or a refresh is rejected.

At minimum, call the userinfo endpoint on each page load or at a short interval; a `401` means the token was revoked. For immediate sign-out, register a **Sign-out notification URL** (OpenID Connect Back-Channel Logout 1.0). Protokol sends a `POST` with a signed `logout_token` (a JWT, header `typ: logout+jwt`) as soon as a sign-in session ends. The URL must be `https` and on the same registrable domain as one of your redirect URIs.

Validate the token: signature against the JWKS, `typ`, `iss`, `aud`, expiry, the back-channel logout event, no `nonce`, and an unseen `jti`. Then end every session for that `sub` and `project_id`, and reply `200`. Respond within five seconds.

## A short worked example

You build an internal tool for your team.

1. Create a private web app with a `https` Launch URL and a callback redirect URI on the same domain. Request only `openid profile email`, so it needs no API permissions.
2. Members see it under **Your apps**. Opening it hits your Launch URL, your app checks `iss`, and starts the authorize request with `prompt=none` and the `project_id` it received.
3. First-time users approve the consent screen once. After that, sign-in is silent.
4. Register a Sign-out notification URL so a removed member loses their session immediately.

## Learn more

- [Web apps](https://docs.protokol.io/platform/web-apps/?ref=blog.protokol.io)
- [Sign in with Protokol (OIDC)](https://docs.protokol.io/platform/oauth-oidc/?ref=blog.protokol.io)