Setting up oasdiff
End-to-end guide covering everything you (the user) and your GitHub organization admin need to have in place for oasdiff to work, plus a troubleshooting table covering every error message the review page can show.
Quick start
Sign in serves two distinct purposes. Pick the one that matches what you want to do:
- View a free change review. Someone shared an oasdiff review URL with you (typically from a pull-request notice), and you want to see the side-by-side breaking-change report. Sign in at oasdiff.com/register via the "View a free change review" card. No setup, no trial counter.
- Start a free Pro trial. You want PR comments, the approve/reject workflow, and commit-status checks on your team's repositories. Visit oasdiff.com/start-trial — that signs you in with GitHub and activates a 30-day Pro trial (no credit card). The dashboard then walks you through installing the GitHub App and adding a workflow file. If you're already signed in but haven't started a trial yet, the same button is available on /dashboard.
If your repository is public and your GitHub organization has no SAML SSO or OAuth-app restrictions, the path above is everything you need. If any of those apply, the sections below cover the additional steps.
For users (signing in and reviewing changes)
Sign in
Sign in to oasdiff at oasdiff.com/register using the same GitHub account that has access to the repositories you want to review. Signing in by itself does not start a Pro trial. To start one, visit oasdiff.com/start-trial instead — same sign-in flow, plus it activates a 30-day Pro trial when you arrive at the dashboard.
If you have multiple GitHub accounts (e.g. work and personal) and the wrong one is currently signed in to github.com, GitHub will use that one when oasdiff redirects through it. To switch first: sign out of github.com, sign back in there as the right account, then return to oasdiff.com/register.
On the GitHub authorization screen, find the Organization access section
When you first sign in to oasdiff, GitHub shows two sections on the authorization screen: Personal user data (the information oasdiff is asking to see) and Organization access (a per-organization list of every organization you belong to). For each organization that requires approval for third-party applications, you'll see a Grant or Request button next to its name. Click that button before clicking the green Authorize oasdiff button. This is the single most common cause of getting stuck: the Authorize button completes the sign-in even if you didn't click Grant/Request for your organization, and oasdiff then can't read your organization's repositories.
Reviewing changes from a private repository
oasdiff reads spec files using your own GitHub access, so private repositories require an extra permission called repo access. You'll be asked to grant it the first time you open a review for a private repository, not at initial sign-in. Click Grant repository access when asked.
Make sure you have access to the repository in GitHub
oasdiff strictly follows GitHub's access rules: if your GitHub account can't see the repository, oasdiff can't show it to you. Make sure you're either an organization member with read access to the repo or an outside collaborator on it. If you're not, ask the repository owner to add you.
If your organization uses SAML single sign-on
Some organizations require an extra single-sign-on step for third-party apps. If yours does, oasdiff will show you a page with a direct link to your organization's SSO authorization page (typically github.com/orgs/{your-org}/sso). Complete the GitHub SSO step there, then come back to oasdiff and click Refresh access. You may need to sign in again so oasdiff picks up the newly authorized token.
Switching to a different GitHub account
Signing out of github.com does not sign you out of oasdiff.com — the two are independent sessions. To switch GitHub accounts on oasdiff, you need to sign out of oasdiff first, then sign in again with the other account.
Step 1 — sign out of oasdiff: when you're signed in, the top-right of every oasdiff.com page shows a Sign out link. Click it. (As alternatives, you can also sign out from your dashboard or directly at oasdiff.com/api/auth/signout.)
Step 2 — switch your github.com session if needed: if a different GitHub account is currently active on github.com, sign out of github.com and sign back in as the account you want oasdiff to use.
Step 3 — sign back in to oasdiff: oasdiff.com/register. GitHub will run a fresh authorization through whichever account is currently signed in there.
For GitHub org admins
oasdiff has two separate GitHub integrations. They are independent — you can approve one without the other. Most teams want both: together they cover the "view a breaking change report on oasdiff.com" flow and the "see a breaking change comment on the pull request itself" flow.
1. OAuth app approval (lets oasdiff read your org's private repos for signed-in members)
Needed if your organization has restricted third-party OAuth applications. Sign-in itself still works without this approval (it's a personal GitHub action). What fails is reading your organization's private repositories on oasdiff's behalf: GitHub blocks the read even though the member has access. The review page surfaces a wall with a direct link to your authorization page so the member can request approval (or grant it themselves if they're an org owner).
Approving the OAuth app does not give oasdiff any standing access to your code or your organization. It only allows each member to authorize their own personal GitHub access for oasdiff to read on their behalf. The information oasdiff requests is minimal:
| What oasdiff asks for | Why |
|---|---|
| GitHub profile (username and avatar) | Identify who is signed in. |
| Primary email address | Account record so the user can be contacted. |
| Repository read access (only when the user opens a review) | Read the OpenAPI spec file from the repository the user is reviewing. Requested on demand when the user opens a review for a private repository, not at sign-in. Each user's access is whatever their GitHub account already grants them. |
To approve: go to your organization's OAuth application policy page at https://github.com/organizations/{YOUR_ORG}/settings/oauth_application_policy. You'll see oasdiff either as a pending request (a member has tried to use it) or in the denied list (a prior request was declined). Click Approve. This is a one-time action per organization.
2. Install the oasdiff GitHub App on your repositories
Needed for the pull-request comment and the oasdiff / API changes status check on pull requests. The App posts as oasdiff[bot] (its own identity, not impersonating any user).
| Permission | Access | Used for |
|---|---|---|
| Metadata | Read | Mandatory for all GitHub Apps. |
| Pull requests | Read & write | Post and update the oasdiff PR comment. |
| Commit statuses | Read & write | Set the oasdiff / API changes check on the PR head commit. |
The App does not request access to code (Contents), issues, branches, actions, secrets, or any other resource. Code is never read by the App. OpenAPI spec files are fetched separately using each reviewing user's own OAuth token, so spec access strictly follows that user's GitHub permissions.
To install: visit github.com/apps/oasdiff/installations/new, select your organization, and choose either All repositories or a specific list. You can change the list later from the App's configuration page.
3. Grant repo access to your users
oasdiff never reads repo content with its own credentials — only with the reviewing user's OAuth token. Each user who needs to review a private repo must have read access to it (org member with role-based access, team membership, or outside collaborator). A user who isn't a collaborator will see an "Access denied" wall on oasdiff.
4. (Optional but recommended) Branch protection
For Pro's "block merge until reviewed" feature, add oasdiff / API changes to the required status checks on your protected branches. Without this, the commit status is informational only and won't prevent merging.
Template email an engineer can send their admin
Replace the curly-braced placeholders and send:
Subject: Approve oasdiff for {ORG} on GitHub
Hi {ADMIN_NAME},
I'd like to use oasdiff (https://oasdiff.com) on our APIs. It detects breaking changes in OpenAPI specs and surfaces them on pull requests so we catch them before they ship.
Because {ORG} enforces SAML SSO and/or OAuth-app approval on GitHub, I need your help with two one-time approvals:
1. Approve the oasdiff OAuth app for {ORG}
Go to https://github.com/organizations/{ORG}/settings/oauth_application_policy
Find "oasdiff" in the pending requests list and click Approve.
2. (For the pull-request comment feature) Install the oasdiff GitHub App on the repos we want covered
Go to https://github.com/apps/oasdiff/installations/new
Select {ORG} and choose either "All repositories" or specific repos.
oasdiff publishes the full list of permissions it asks for and what each one is used for here:
https://oasdiff.com/docs/setup
Happy to forward you the security overview or jump on a quick call if you'd like more detail.
Thanks,
{YOUR_NAME}Four organization-side states for the OAuth app
On your organization's OAuth application policy page, oasdiff can sit in one of four states. Which one your organization is in determines whether reviews work and what the recovery is:
| State | What it means | What to do |
|---|---|---|
| Approved | Your organization allows oasdiff to access its data. | Nothing — reviews work. |
| Pending request | A member asked for approval and an organization owner hasn't acted yet. | An organization owner clicks Approve on the OAuth application policy page. |
| Not yet requested | Your organization restricts OAuth apps but no one has tried oasdiff yet, or someone authorized without clicking the per-organization Grant/Request button. | The user opens their oasdiff authorization page on GitHub (the review page's error message links there directly) and clicks Grant (organization owners) or Request (members). |
| Denied | An organization owner explicitly denied oasdiff. Shows as a red X on the user's authorization page. | Only an organization owner can lift the denial, on the OAuth application policy page. The user's authorization page offers no recovery. Email your admin using the template above. |
Troubleshooting: what each error message means
If you opened a review URL and saw an error message instead of the side-by-side diff, find the heading you saw in the table below:
| Error message heading | What it means | What to do |
|---|---|---|
| Sign in to review the changes | You're not signed in to oasdiff yet. | Click Sign in with GitHub. If you have multiple GitHub accounts and the wrong one is signed in on github.com, sign out of github.com first so the right one is picked up. |
| Private repository | You're signed in but haven't granted oasdiff permission to read your private repositories yet. | Click Grant repository access. GitHub will ask you to add the repository-read permission, then bring you back to the review. |
| Authorization required for SSO | Your organization requires single sign-on, and your GitHub access for oasdiff hasn't been authorized through it yet. | Click the SSO authorization link on the page, complete the GitHub single sign-on flow, then click Refresh access back on the review page. |
| Grant oasdiff access to {your-org} | Your organization restricts third-party OAuth apps and oasdiff hasn't been approved on its allowed list. | Click Grant oasdiff access to {your-org}. If you're an organization owner you'll see a Grant button there — one click. If you're a member, you'll see a Request button that notifies your organization owners. Once approved, click Refresh access. |
| Access denied | GitHub is saying your account doesn't have access to this specific repository. | Either ask the repository owner to add you as a collaborator, or sign in with a different GitHub account that has access (the error page offers a switch-account option). |
What oasdiff stores, transmits, and never sees
- OpenAPI spec content is transient. Specs are fetched on demand to compute the diff and render the review page, and discarded immediately. They are never persisted to the oasdiff database.
- Reviewer OAuth tokens are session-only. Stored in an HTTP-only cookie on the reviewer's browser. Never written to the oasdiff database.
- GitHub App installation tokens are short-lived and in-memory only. Cached per repository for at most one hour; never persisted to disk or database.
- The GitHub App is used only for writes oasdiff performs under its own identity (PR comments, commit statuses). It is never used to read repository contents on behalf of a user.
- What is stored: the signed-in user's GitHub username, email, and avatar URL; the repository owner, name, and pull-request number for each report; the per-change review decisions and the reviewer's GitHub username; subscription state.
For the full data inventory and legal basis, see the privacy policy.
Common questions
Do I have to start a Pro trial to use oasdiff?
No. Signing in at oasdiff.com/register does not start a trial. If you only want to view a free change review someone shared with you, that's the right URL — sign in and head back to the review. The Pro trial only activates when you specifically visit oasdiff.com/start-trial or click Start free Pro trial on your dashboard. The CLI and the free GitHub Action don't require any oasdiff account at all.
Does approving the OAuth app give oasdiff access to our code?
No. Approving the OAuth app only allows individual members of your organization to sign in to oasdiff.com and authorize their own GitHub token for the org. Each user's access is whatever their personal GitHub account already grants them. The OAuth app itself has no standing server-side credential against your organization.
Does installing the GitHub App give oasdiff access to our code?
No. The App requests only Pull requests: read & write and Commit statuses: read & write. It does not request the Contents permission, which is the one that would grant repository code access.
Can we limit the GitHub App to a few repositories first?
Yes. At install time, choose Only select repositories and pick the ones you want covered. You can add or remove repositories at any time from the App's configuration page on github.com.
Can we revoke approval later?
Yes, both. The OAuth app approval can be revoked from the same oauth_application_policy page. The GitHub App can be uninstalled from the organization settings under Installed GitHub Apps. Revocation takes effect immediately.
We use the CLI and the free GitHub Action only. Do we need to approve anything?
No GitHub-side approval is needed to run the CLI or the free GitHub Action. The CLI runs entirely on the user's machine. The free Action runs inside your own CI and uses your repository's built-in GITHUB_TOKEN, not any oasdiff-owned credential. The approvals on this page are only needed for the oasdiff.com review surface and for the Pro pull-request comment.
Get help
Email info@oasdiff.com with any setup, security, or procurement questions. We can also walk through the approval steps with your IT or Security team on a short call.