Register an app

How to register an app that connects to Penv Cloud: the console page, fields, client_id, redirect URI rules, testing mode, domain proof, verification, and what happens on suspension or deletion.

Any organization can register an app. The app can then send people through the connect flow. A new app is in testing mode until we verify it.

Where

In the console, open Developer > Apps for your organization. Creating, editing, submitting and deleting apps needs the app:manage permission. Owners and admins hold it; a custom role holds it only if you add it. Members can view apps.

To create or change an app you also need a verified email address and two-factor authentication on your account. An app belongs to the organization, not to you. It stays when you leave.

Fields

Field	Rule
Name	2 to 40 characters. It cannot contain "penv" or "penvhq", ignoring case, spaces and punctuation. It cannot match a verified app's name.
Icon	PNG, JPEG or WebP, square, 64 to 1024 pixels, up to 256 KB. Uploaded, not linked. It shows only once the app is verified. Until then people see a letter.
Homepage	An `https` address on a host you control. Required to submit for verification.
Description	Short text shown on the approval page.
Redirect URIs	See below. Up to 10.

client_id

We give each app a client_id that starts with app_. Use it as client_id on /connect and at the token and exchange endpoints.

Apps are public clients. There is no client secret. PKCE with S256 is required on every connection. The id is not secret, and we never reuse one.

Redirect URIs

We compare the redirect_uri with your list exactly, character for character. A URI that is not on the list is refused.

https only. No userinfo, no fragment, no wildcard.
Up to 10 per app, written in canonical URL form.
A Chrome extension may use https://<extension-id>.chromiumapp.org/....
A native or command-line app may use http://127.0.0.1 or http://localhost with any port. When we match, we ignore the port (RFC 8252).
Custom schemes such as myapp:// are not supported.

Testing mode

A new app is unverified. Only members of the organization that owns it can connect it. Anyone else is refused with app_unverified. Use this to build and test.

The approval page shows an "Unverified app" warning, the homepage host, and the host the person will be sent back to.

Submit for verification

Set a homepage.
Prove you control its host. The app page shows a token. Do one of these:
- Add a DNS TXT record on the homepage host: penv-app-verification=<token>.
- Serve the token as the body of https://<host>/.well-known/penv-app.txt.
Choose Submit for verification.

A Penv admin checks the proof and looks at the app. We read the TXT record or the file from our servers. The file must be on https port 443, answer without redirects within 5 seconds, and the host must resolve to a public address.

If we approve, the app is verified and anyone can connect it. If we reject, the app goes back to unverified with a note. Fix what the note says and submit again.

Changes after verification

For a verified app, these edits go back to review. The live values stay as they are until we approve:

name
icon
homepage
a redirect URI on a host we have not approved before

A description change applies at once. So does a redirect URI on a host we already approved.

If you change the name, icon, homepage or redirect URIs of an app that is in review, it goes back to unverified. Our reviewers see the icon you uploaded, and we verify only the values we reviewed.

Suspension and deletion

We can suspend an app, for example after reports. A suspended app is refused with app_unavailable. Suspension revokes every connection, grant and live pck_ from the app at once.

You can delete an app. Deleting also revokes every connection, grant and live pck_ at once. The app then gets invalid_client. The client_id is never reused.

Limits

10 apps per organization.
Creating and editing apps is rate limited.
People can report an app from the approval page. Reports go to our review queue.

Errors

These come from the console when you create or change an app.

Code	Cause
`app_limit_reached`	The organization already has 10 apps.
`invalid_name`, `reserved_name`, `name_taken`	The name breaks the rules above.
`invalid_redirect_uris`	A URI breaks the rules. `problem` says which rule and `index` says which URI.
`invalid_homepage_url`, `homepage_required`	The homepage is not a valid `https` address, or is missing at submit.
`invalid_icon`	The icon is empty, too large, the wrong type, corrupt, or the wrong size.
`invalid_state`	The app is not in a state that allows that action.

Errors that apps see at /connect, token and exchange are in Connect an app.

On this page