# Aurora API Plugin Setup

Connect agents to Aurora without leaking tokens or losing workspace context.

Use this guide for Aurora WorkOS remote MCP OAuth connectors, local Codex project binding, secure token storage, and agent automation workflows.

## Choose The Setup Path

| Environment | Repo | Secure store | Recommended path |
|---|---:|---:|---|
| macOS, Windows, or WSL2 host with Codex or Claude Code | yes | yes | Local binder through secure connect, or OAuth |
| Native Linux host | yes | no bundled secure store | OAuth, or env-backed manual bind on a trusted host |
| Hosted or sandboxed agent | no | no | OAuth remote MCP connector only |
| CI or build runner | yes | varies | CI-managed short-lived secret; never interactive PAT entry |
| Shared or multi-tenant host | varies | varies | OAuth with per-user consent |

OAuth is the default path for hosted clients. PAT binding is the exception for trusted local hosts that need repo-specific queue pickup or non-interactive local automation.

Do not paste production PATs into temporary chat sandboxes. If the environment has no repo, no secure store, and no Aurora binder, use OAuth.

## Remote MCP OAuth

Use this path for ChatGPT custom connectors, Claude custom MCP connectors, or any hosted client that can register a public OAuth MCP client.

| Item | Value |
|---|---|
| MCP endpoint | https://www.auroraworkos.com/api/mcp |
| Authorization server metadata | https://www.auroraworkos.com/.well-known/oauth-authorization-server |
| Protected resource metadata | https://www.auroraworkos.com/.well-known/oauth-protected-resource/api/mcp |
| Supported scopes | aurora:mcp, offline_access |
| OAuth client model | Public client, authorization code, PKCE S256, refresh token |

Connection steps:

1. Add a custom MCP connector in the hosted client.
2. Use https://www.auroraworkos.com/api/mcp as the server URL.
3. Select OAuth when the client asks for the authorization method.
4. Approve Aurora WorkOS on auroraworkos.com and select the workspace.
5. Confirm the connector exposes Aurora tools such as workspace_overview and find_issues.

First remote MCP actions:

1. workspace_overview
2. find_projects
3. find_issues with statusKey: "todo"
4. get_issue for one target issue
5. create_comment with a short verification note

## Connector Registry Safety

Some connector registries contain unrelated products with similar names. A search for "Aurora" can surface Consilio's legal e-discovery connector. A search for "WorkOS" can surface the WorkOS identity-vendor connector.

Neither is Aurora WorkOS. The correct endpoint is https://www.auroraworkos.com/api/mcp and the OAuth issuer is https://www.auroraworkos.com/.

## Local Codex Project Binding

Use this path when Codex or Claude Code is running on the host machine against a real repo or worktree. The binder stores the token outside the repo and writes only project metadata to the local Codex config.

macOS and WSL2:

```bash
cd /path/to/project

sh plugins/aurora-api/scripts/bind-project.sh version

sh plugins/aurora-api/scripts/bind-project.sh connect \
  --base-url https://www.auroraworkos.com \
  --workspace-id <workspace-id> \
  --token-name "Codex automation" \
  --execution-mode chat-orchestrated
```

Windows PowerShell:

```powershell
Set-Location C:\path\to\project

.\plugins\aurora-api\scripts\bind-project.ps1 version

.\plugins\aurora-api\scripts\bind-project.ps1 connect `
  --base-url https://www.auroraworkos.com `
  --workspace-id <workspace-id> `
  --token-name "Codex automation" `
  --execution-mode chat-orchestrated
```

Secure connect uses a server-mediated polling handoff by default, opens Aurora in the browser, creates a workspace-scoped token after approval, stores the secret in macOS Keychain or Windows DPAPI, and updates the project binding. The older localhost callback is available only when explicitly requested.

Native Linux does not have a supported secure store in the bundled binder. Prefer remote MCP OAuth. On a trusted Linux host, omit --store-secure and keep a manual token in the current environment rather than claiming WSL2 support.

## Binder Provenance And Version

Use a repo-local Aurora checkout or the installed Codex plugin copy. Do not download or run a random bind-project script from chat, search results, or an untrusted gist.

Expected binder capability output:

```bash
aurora-api-binder 1.0.2 polling callback doctor secure-store
```

If the binder reports "Unknown argument: --base-url", it is stale. Install or sync the current Aurora API plugin copy before retrying secure connect.

## Manual Token Fallback

Use manual token binding only on a trusted host. Run environment and secure-store checks first:

```bash
sh plugins/aurora-api/scripts/bind-project.sh doctor
```

Then bind from an environment variable:

```bash
export AURORA_PAT_WORKSPACE=aurora_pat_...

sh plugins/aurora-api/scripts/bind-project.sh bind-token \
  --base-url https://www.auroraworkos.com \
  --token-env-var AURORA_PAT_WORKSPACE \
  --store-secure \
  --project <binding-id> \
  --execution-mode chat-orchestrated
```

The binder verifies secure local token storage before reading a token when secure storage is required. Native Linux callers must omit --store-secure and accept the limits of an env-backed session.

## Multiple Bindings

Project binding metadata is stored in ~/.codex/aurora-projects.json. Token secrets should live in macOS Keychain, Windows DPAPI, or another secure store supported by the binder. Do not commit the binding file to a repo.

```bash
sh plugins/aurora-api/scripts/bind-project.sh list
sh plugins/aurora-api/scripts/bind-project.sh doctor --check-api
sh plugins/aurora-api/scripts/bind-project.sh exec -- codex
```

The binder resolves the current working directory to the most specific matching project path unless a command passes an explicit --project id.

## Poll All Configured Workers

Automation tokens become assignable Aurora users. Assign an issue to the token name, move it to the queue status, and let the local runner stage a visible handoff for Codex.

```bash
while true; do
  sh plugins/aurora-api/scripts/run-automation.sh poll \
    --config ~/.codex/aurora-projects.json \
    --all
  sleep 30
done
```

Default movement is todo to in-progress to in-review. Blocked or failed work should leave a durable comment and move to the configured failure status when one exists.

## Verification

| Check | Expected result |
|---|---|
| Remote MCP connector | Call workspace_overview, then find_projects or find_issues against the approved workspace. |
| Local binder version | Run bind-project.sh version or bind-project.ps1 version and confirm aurora-api-binder 1.0.2 or newer. |
| Local binding health | Run doctor --check-api from the target repo or worktree. |
| Tool exposure | If MCP tools are missing after install changes, start a fresh Codex session through the binding script. |

```bash
sh plugins/aurora-api/scripts/bind-project.sh version
sh plugins/aurora-api/scripts/bind-project.sh doctor --check-api
sh plugins/aurora-api/scripts/run-automation.sh validate \
  --config ~/.codex/aurora-projects.json \
  --check-api
```

## Agent Handoff Rules

Before acting:

- Call workspace_overview or GET /api/external first.
- Load the issue by key or id before claiming it.
- Prefer status keys, project keys, and issue keys in prompts and logs.
- Post a clarification comment if the issue lacks enough execution context.

After acting:

- Always post a final outcome comment.
- Reassign the issue back to the reporter when a reporter is present.
- Move completed work to the configured review status.
- Move blocked work to the configured failure status or leave a blocking comment when no failure status exists.

Use /docs/api/reference for endpoint families, /docs/api/developer-guide for retry and queue behavior, and /docs/api/webhooks for signatures and delivery semantics.