Aurora API Plugin Setup | Aurora WorkOS

Setup paths

Choose the integration path that matches the agent environment

The right path depends on whether the agent is hosted behind a connector, running locally against a repo, or operating in a temporary sandbox. Start with OAuth unless the agent is on a trusted host with a real repo and secure local storage.

Remote MCP OAuth connector

Best for ChatGPT, Claude, and other hosted clients that support custom remote MCP servers and interactive OAuth approval.

Local Codex project binder

Best for Codex or Claude Code running on the developer machine with a real repo, secure local storage, and project-specific queue pickup.

Manual token fallback

Use only on a trusted host when the browser-based secure connect flow is unavailable. Store the token through the binder, not in chat.

Do not paste production PATs into temporary chat sandboxes

If the environment has no repo, no secure store, and no Aurora binder, use the remote MCP OAuth connector. The manual token fallback is for trusted local hosts only.

Environment routing

Match the setup method to the runtime

Run this check before any token handling. Environments without persistent storage should use OAuth, not PAT binding.

Environment	Repo	Secure store	Recommended path
Host dev machine with Codex or Claude Code	yes	yes	Local binder through secure connect, or OAuth
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

Agent-readable variant

This setup guide is also available as Markdown at /plugins/aurora-api.md.

Hosted connectors

Remote MCP OAuth setup

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

Run the OAuth flow from an interactive browser session.

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

Use the Aurora WorkOS connector, not a lookalike

Some connector registries contain unrelated products with similar names. Treat the domain and OAuth issuer as the source of truth.

Registry warning

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

Bind a local project to an Aurora workspace

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, Linux, and WSL2

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

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 behavior

The connect command starts a localhost callback, opens Aurora in the browser, creates a workspace-scoped token after approval, stores the secret in the host secure store, and updates the project binding.

Distribution and version

Use a trusted binder copy and verify capabilities

The binder handles workspace credentials. Use a repo-local Aurora checkout or the installed Codex plugin copy; do not run bind scripts from chat, search results, or untrusted snippets.

Expected version output

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

Stale binder signal

If connect fails with Unknown argument: --base-url, the binder copy is stale. Sync or install the current Aurora API plugin before retrying secure connect.

Fallback

Manual token binding is for trusted hosts only

Use manual token binding only when secure connect is unavailable and the operator controls the host. Run preflight before token entry.

Preflight first

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

Manual secure-store bind

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

Fail-closed token handling

When secure storage is required, the binder verifies macOS Keychain or Windows DPAPI availability before reading the token. If that check fails, stop and use the remote MCP OAuth connector instead.

Project mapping

Support multiple Aurora bindings on one machine

Use one binding per repo, worktree, workspace, or automation identity. The binder resolves the current working directory to the most specific matching project path unless a command passes an explicit project id.

List, inspect, and launch through a binding

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

Local storage locations

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.

Queue pickup

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.

Continuous polling

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

Default queue movement

A queued issue starts in todo, is claimed into in-progress, and should be finalized into in-review or a configured failure state with a durable comment.

Validation

Verify the connector before assigning real work

Check the endpoint, binding version, token health, and tool exposure before using the integration for production work.

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.

Local verification commands

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 workflow

Required handoff behavior for AI agents

Agents should leave Aurora in a useful state for the human who assigned the work.

Before acting

Resolve workspace context and confirm the target issue before making changes.

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

Return the task with a durable summary so the board tells the truth.

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.

Need the full API surface?

Use the API reference for endpoint families and the developer guide for retry, queue, and structured-error behavior.

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

Canonical endpoints