Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
<!---
Provide a short summary in the Title above. Examples of good PR titles:
* "Feature: "
* "Fix: "
* "Update: "
-->

## Why are we changing this?

<!---
- Make it easy understand, write it for people outside your team.
- You can copy paste jira for "What/Why" or add any related stories/prs that help give the reviewer context.
-->

## What has changed?

<!---
- You know the ins and out of the code, the reviewer might not.
- Add any specific implementation details or anything non-obvious that a reviewer should look out for.
-->

## How to test it and expected results?

<!---
- Make it easy to test, give explicit step-by-step instructions, e.g. commands, screenshots and/or videos of what to do.
- Make it obvious it works, include screenshots or pastes of output so it's clear what the reviewer should expect.
-->

## Checklist:

<!---
This checklist is mostly useful as a reminder of small things that can easily be
forgotten – it is meant as a helpful tool rather than hoops to jump through.
Put an `x` in all the items that apply, make notes next to any that haven't been
addressed, and remove any items that are not relevant to this PR.
-->

- [ ] My pull request represents one logical piece of work.
- [ ] My commits are related to the pull request and look clean.
- [ ] My code follows our coding conventions.
- [ ] My code has appropriate tests and documentation.
31 changes: 26 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Agent usage mapping is documented in `docs/agent-command-map.md`.
## Features in this scaffold

- Profile-based auth in `~/.omni/config.json`
- Supports both PAT and org API key tokens
- Supports PAT auth, org API keys, or both in one profile
- Token storage backends: `keychain` (macOS) or `config` fallback
- Config precedence: flag > env > config file
- `omni setup` wizard (interactive + non-interactive)
Expand Down Expand Up @@ -56,7 +56,8 @@ Agent usage mapping is documented in `docs/agent-command-map.md`.
- `--profile`
- `--url`
- `--token`
- `--token-type pat|org`
- `--auth pat|org`
- `--token-type pat|org` (legacy override)
- `--config`
- `--json`
- `--plain`
Expand All @@ -67,6 +68,9 @@ Agent usage mapping is documented in `docs/agent-command-map.md`.

- `OMNI_PROFILE`
- `OMNI_URL`
- `OMNI_AUTH`
- `OMNI_ORG_KEY`
- `OMNI_PAT` (manual override; PAT is normally acquired by browser login)
- `OMNI_TOKEN`
- `OMNI_TOKEN_TYPE`
- `OMNI_CONFIG`
Expand Down Expand Up @@ -109,9 +113,12 @@ omni completion fish > ~/.config/fish/completions/omni.fish

```bash
omni setup
omni setup --non-interactive --profile prod --url https://acme.omniapp.co --token "$OMNI_PAT" --token-type pat --token-store auto
omni --no-input setup --profile prod --url https://acme.omniapp.co --token "$OMNI_PAT" --token-type pat
omni auth add --name prod --url https://acme.omniapp.co --token "$OMNI_PAT" --token-type pat --token-store keychain
omni setup --profile prod --url https://acme.omniapp.co --auth-mode pat --token-store auto
omni setup --non-interactive --profile prod --url https://acme.omniapp.co --auth-mode org --org-key "$OMNI_ORG_KEY" --token-store auto
omni setup --profile prod --url https://acme.omniapp.co --auth-mode both --org-key "$OMNI_ORG_KEY" --default-auth pat
omni --no-input setup --profile prod --url https://acme.omniapp.co --auth-mode org --org-key "$OMNI_ORG_KEY"
omni auth add --name prod --url https://acme.omniapp.co --auth-mode both --org-key "$OMNI_ORG_KEY" --default-auth pat --token-store keychain
omni --auth org documents list --page-size 20
omni schema
omni schema documents permissions
omni exit-codes --json
Expand Down Expand Up @@ -160,6 +167,20 @@ omni query run --file query.json --result-type json --wait
omni jobs status 12345
```

## Auth model

- `omni setup` asks what auth to configure: `pat`, `org`, or `both`
- PAT setup uses browser login rather than asking the user to paste a token
- Profiles can store both a PAT and an org key at the same time
- General commands use the profile's `default_auth`
- Org-only commands such as `admin`, `users`, and `scim` automatically use the org key
- `--auth pat|org` forces a specific credential for the current command
- `OMNI_PAT`, `--token`, and `--token-type` are still accepted as manual/legacy overrides

See also:

- `docs/pat-auth-flow.md`

## Command overview

- `omni setup`
Expand Down
105 changes: 105 additions & 0 deletions docs/pat-auth-flow.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
# PAT Auth Flow

This document explains how PAT authentication works in `omni-cli` and why it is implemented as a browser login flow instead of a pasted secret.

## Summary

- PAT is not treated as a user-entered API key in this CLI
- PAT setup uses a browser-based OAuth flow
- Org API key setup is still a direct prompt/input flow
- A profile can store:
- `pat`
- `org`
- `both`
- General commands use the profile's `default_auth`
- Org-only commands such as `admin`, `users`, and `scim` always use the org key

## Why

The main Omni API docs distinguish normal API-key usage from MCP OAuth PAT usage. In practice, the PAT flow used by Omni MCP is browser/OAuth based. That means prompting users to paste a PAT during setup is the wrong UX and the wrong model.

## What We Verified

We checked:

- Omni MCP docs
- Omni API authentication docs
- The published `@omni-co/mcp` npm package
- The hosted OAuth discovery metadata on `callbacks.omniapp.co`

Important finding:

- The published `@omni-co/mcp` package does not implement the browser auth flow itself. It is an API-key bridge.
- The usable PAT auth contract comes from Omni's public OAuth discovery metadata, not from the npm package contents.

## OAuth Endpoints Used

These endpoints were publicly discoverable and used to implement PAT login:

- Protected resource metadata:
- `https://callbacks.omniapp.co/.well-known/oauth-protected-resource`
- Authorization server metadata:
- `https://callbacks.omniapp.co/.well-known/oauth-authorization-server`
- Dynamic client registration:
- `https://callbacks.omniapp.co/oauth/register`

Observed metadata includes:

- authorization endpoint:
- `https://callbacks.omniapp.co/callback/mcp/oauth/authorize`
- token endpoint:
- `https://callbacks.omniapp.co/callback/mcp/oauth/token`
- scope:
- `mcp:access`
- PKCE:
- `S256`
- dynamic client registration:
- supported
- token endpoint auth method:
- `none`

## Implemented PAT Flow

The CLI PAT login flow is:

1. Fetch protected resource metadata
2. Fetch authorization server metadata
3. Dynamically register a native OAuth client
4. Start a localhost callback listener on `127.0.0.1`
5. Generate PKCE verifier/challenge and state
6. Open browser to Omni authorization endpoint
7. Receive authorization code on loopback callback
8. Exchange code for bearer token
9. Store the returned token as the PAT credential for the profile

The implementation lives in:

- [internal/cli/pat_login.go](/Users/hawkfry/Documents/open-source/omni-opensource/omni-cli/internal/cli/pat_login.go)

## Public Repo Caveat

This repo is public. The current PAT implementation is considered acceptable to keep in a public repo because:

- it uses public OAuth discovery metadata
- it uses standard OAuth 2.1 native-app patterns
- it does not expose secrets or bypass intended auth behavior

But this should be treated as a currently working public integration point, not as a guaranteed permanent Omni CLI contract.

In other words:

- the flow is public enough to use
- the stability is not guaranteed unless Omni explicitly documents it as a supported standalone CLI auth contract

If Omni changes hosted OAuth endpoints or MCP-related auth behavior, this implementation may need to be updated.

## If This Breaks Later

Re-check:

- Omni MCP docs
- Omni API auth docs
- `callbacks.omniapp.co` OAuth discovery metadata
- whether Omni still supports loopback redirect URIs via dynamic client registration

Do not reintroduce PAT as a pasted token during setup unless Omni explicitly changes their supported auth model.
Loading
Loading