> ## 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.

# OAuth 2.0: let apps act on a user's behalf, with consent
- URL: https://blog.protokol.io/oauth2/
- Published: 2026-11-17T17:33:08.000Z
- Updated: 2026-11-17T19:14:57.000Z
- Description: Register an OAuth client, run the authorization code flow with PKCE, and let users approve exactly what your app may do in their project, with Sign in with Protokol (OpenID Connect) on top.
- Author: Strahinja Djuric
- Tags: Engineering, Security

Sometimes an app that is not part of your project needs to call the Protokol API as a user: a script, a CLI, a server-side integration, a mobile app. Protokol uses the standard OAuth 2.0 authorization code flow with PKCE instead. The user signs in, sees exactly what the app can do, and approves or denies it.

If you are building a site that people open from Protokol with a Launch URL, create a web app instead: see [Web apps: sites people open from Protokol and sign in to](https://blog.protokol.io/web-apps/). This post covers registering an OAuth client, the flow and tokens, scopes and consent, what users and project admins can control, Sign in with Protokol (OpenID Connect), and the security notes you should know before you ship.

## Register a client

A project admin creates the client in the dashboard: open **OAuth** in the sidebar, choose **Clients**, then **Create client**. The main fields:

| Field                | What it does                                                                                                                       |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Name                 | Shown to users on the consent screen                                                                                               |
| Client type          | **Public** for code that cannot keep a secret (single-page apps, mobile apps, CLIs). **Confidential** for server-side code         |
| Access type          | **User connection** acts as the signed-in person. **Project installation** acts for the project and requires a confidential client |
| Application type     | Web or Native, which decides which redirect URIs are accepted                                                                      |
| Redirect URIs        | Exact callback URIs your app uses                                                                                                  |
| Allowed permissions  | The most your app may ever request                                                                                                 |
| Allow refresh tokens | Required if the app will request offline\_access                                                                                   |
| Token policy         | Optional access token lifetime (60 to 900 seconds) and, for public clients, refresh token lifetime (1 hour to 30 days)             |

![The Create OAuth client form filled in for a public client named Acme Mobile with a redirect URI and three allowed permissions](https://blog.protokol.io/content/images/2026/11/01-create-client.png)  
*Creating a public client: name, redirect URI and the permissions it may request.*

For a confidential client the client secret is shown once, so copy it into your secret store. You can rotate it later, and the previous secret keeps working for the grace period you configured. The client id looks like `pk_cli_…`.

Redirect URIs are matched exactly. Web apps use an `https://` URI with no wildcards and no fragments. Native apps can also use a reverse-domain scheme such as `com.example.app:/callback` or a loopback URI like `http://127.0.0.1:PORT/path`.

A new client works only in the project that owns it. To let users connect it in other projects, choose **Request publication**. Protokol reviews it, and once approved, any project can authorize it, subject to that project's own app policy.

## The flow

Only the `code` response type and the S256 PKCE method are supported. The supported grant types are `authorization_code` and `refresh_token`.

1. Your app creates a `code_verifier` and sends its SHA-256 hash as the `code_challenge`, plus a `state`.
2. It sends the user to `/v1/oauth/authorize`.
3. The user signs in, reviews the consent screen and approves.
4. Protokol redirects to your `redirect_uri` with `code`, `state` and `iss`.
5. Your app exchanges the code for tokens at `/v1/oauth/token`.

The authorize request looks like this:

```
GET https://lemon.protokol.io/v1/oauth/authorize
  ?response_type=code
  &client_id=pk_cli_0123456789abcdef0123456789abcdef
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
  &project_id=YOUR_PROJECT_ID
  &state=STATE_FROM_STEP_1
  &code_challenge=CHALLENGE_FROM_STEP_1
  &code_challenge_method=S256
  &scope=perm64%3AcmVhZCBwcm9kdWN0cw%20offline_access

```

On the callback, check that `state` matches what you stored and that `iss` equals the issuer from the discovery document. The code is single-use and expires after 10 minutes. Then exchange it (the body is form-encoded, not JSON):

```
curl -X POST https://lemon.protokol.io/v1/oauth/token \
  -d grant_type=authorization_code \
  -d client_id=pk_cli_0123456789abcdef0123456789abcdef \
  -d code=pk_ac_CODE_FROM_REDIRECT \
  -d redirect_uri=https://app.example.com/callback \
  -d code_verifier=VERIFIER_FROM_STEP_1

```

A confidential client authenticates with its secret instead (`-u 'CLIENT_ID:YOUR_CLIENT_SECRET'`). The response holds the `access_token`, its `expires_in`, the granted `scope`, and the `project_id` the token is bound to. Send the token as `Authorization: Bearer <access_token>`.

A token is issued for one user in one project, so you send no project header, and calls always act in that project. Access tokens last 15 minutes by default.

### Refresh tokens

Request `offline_access` to get a refresh token and renew access without asking the user again. Public clients rotate the refresh token on every use: store the new one before you use it, and never refresh concurrently, because reusing an old token ends the session. Confidential clients keep the same refresh token. Treat `invalid_grant` as "sign the user in again".

Call `/v1/oauth/revoke` when the user signs out; confidential clients can use `/v1/oauth/introspect`. Discovery is public at `/.well-known/oauth-authorization-server`, so read endpoints and issuer from there.

## Scopes and consent

Each scope token is a Protokol permission name, encoded as `perm64:<base64url of the name>`. For example, `read products` becomes `perm64:cmVhZCBwcm9kdWN0cw`:

```
printf '%s' 'read products' | basenc --base64url | tr -d '='

```

You can also request a pattern with `pattern64:`, which is expanded at authorization time to the exact permissions that exist. `offline_access` is a plain token, not a permission.

What the app actually gets is the intersection of three things, minus anything the user unticks on the consent screen:

- what the app requests;
- what the client is allowed to request;
- what the signed-in user can do in that project.

A user cannot hand an app more than they hold themselves. The token response `scope` lists the final permissions, so read it instead of assuming you got everything. Adding permissions later always needs the user's consent: run the flow again with a larger `scope`.

Requests that send `X-Project-Env: dev` are rejected unless the token includes `dev env_access`, and the user must hold it too.

## What users and admins control

Users and project admins can disconnect apps from the dashboard (**OAuth → Connected apps**, and **Authorized apps** in the account menu). Project admins can also restrict which apps their members may connect under **OAuth → App policy**. A client blocked by the policy gets `unauthorized_client` at authorization, so if you publish an app, ask admins to add it to their allow-list when a project uses that policy.

Public clients that users of other projects sign in to (a CLI, a mobile app) need an install by a project admin, who can optionally limit it to some workspaces. Uninstalling revokes the access of the project's members.

## Sign in with Protokol (OpenID Connect)

If you only need to know who the user is, add `openid` to the scope. Protokol implements OpenID Connect Core 1.0 on the same flow, with `response_type=code` and PKCE only (no implicit or hybrid flow).

- **Discovery:** `/.well-known/openid-configuration`, with signing keys at `/.well-known/jwks.json`.
- **Scopes:** `openid` returns an `id_token`; `profile` adds `name` and `email` adds `email` and `email_verified`, both read from the userinfo endpoint. The user can untick the last two.
- **ID token:** a JWT signed with RS256, valid for 5 minutes. Claims include `iss`, `sub`, `aud`, `azp`, `iat`, `exp`, `auth_time`, `nonce` and `at_hash`. It carries no name or email.
- **Parameters:** `nonce`, `prompt` (`none`, `login`, `consent`, `select_account`) and `max_age`.

Identify users by `sub` together with the issuer, never by email. `sub` is stable and is the same for a user across all apps. An app that requests only `openid profile email` needs no API permission at all. A client with the Project installation access type cannot request `openid`.

## Security notes

The security model says: whoever can change or deploy code can read every secret that code receives. Two lines apply directly to OAuth:

- An OAuth app that may deploy code is trusted like a developer. Deployed code receives the project secrets of the user who deploys it.
- Approving an app trusts its code, including later versions you approve, within the permissions you approved.

An OAuth token that writes code chooses a [run identity](https://blog.protokol.io/run-identities/) as its user would, and the same rules apply to every client: the dashboard, the API, the toolkit and OAuth clients. If your app can create API users, it needs `edit base_users` and `credentials::manage base_users`. The new user can only get roles whose permissions the token holds, and admin roles are never allowed. Those API users are not revoked when the user disconnects the app, so delete them separately.

## A short worked example

You build a CLI that lists products.

1. Create a **Public** client with a **User connection** access type, a loopback redirect URI, allowed permissions `read products`, and refresh tokens enabled.
2. Open the authorize URL in the user's browser with `scope=perm64:cmVhZCBwcm9kdWN0cw offline_access`.
3. Catch the redirect on your loopback port, check `state` and `iss`, and exchange the code.
4. Call the API with the bearer token. When it returns `401` with `invalid_token`, refresh once and retry.

## Learn more

- [OAuth clients](https://docs.protokol.io/platform/oauth/?ref=blog.protokol.io)
- [Sign in with Protokol (OIDC)](https://docs.protokol.io/platform/oauth-oidc/?ref=blog.protokol.io)
- [Security model](https://docs.protokol.io/platform/security-model/?ref=blog.protokol.io)