Skip to main content
The customer starts on your site, approves on Entire, and returns to you.
  1. You send the customer to Entire. Make an unguessable state value, tie it to the customer’s browser session (for example in a signed, HttpOnly cookie), and redirect to:
  2. The customer approves. They sign in to Entire, choose a project they manage, and choose all of its repositories or a list. The page shows the permissions you registered. For repositories:create it shows “Create repositories in this project”. Only people who manage the project can install plugins.
  3. Entire sends the customer back. On approval, the browser returns to your redirect_uri with two query parameters, receipt and state. If the customer cancels, it returns with error=access_denied and the state instead.
  4. You verify the receipt. Check every item in the list below before you trust it.
  5. You store the installation ID. It is the only key you need. Show the customer a confirmation page.

​
Verifying an install receipt

The receipt is a compact JWT signed with EdDSA. The SDK’s App.AcceptReceipt does all of this:
  • The state query parameter equals the state you stored for this browser session. Compare in constant time. A mismatch is a forged or replayed callback.
  • The header typ is entire-install-receipt+jwt, and alg is EdDSA.
  • The iss claim is one of Entire’s Cores. Check this before you fetch keys, because the issuer decides where the keys come from.
  • The signature verifies against the key named by kid in the issuer’s JWKS at {iss}/.well-known/jwks.json.
  • aud includes urn:entire:plugin:{slug}, and plugin_id is your slug.
  • exp has not passed. Receipts last five minutes, so verify them as soon as they arrive.
  • The state claim inside the receipt equals your stored state.
  • You have not accepted this jti before.
The verified receipt carries installation_id, project (the project’s name) and project_id.

​
Key installations on their ID alone

Installations are global. Any Core serves any installation, and the receipt’s issuer only tells you which Core handled the consent. Do not key your records on the issuer, and do not assume the installation belongs to one region. Call whichever Core is nearest your service.