Aurora WorkOS

API quickstart

Get Aurora talking to your client in one pass: token, discovery, first read, first write.

Aurora's external API is built for automation clients, operators, and AI workflows that need stable workspace discovery before mutation. This quickstart gets you from zero to a working integration path without having to infer the contract from endpoint names alone.

Quickstart highlights

  • Workspace-scoped bearer-token API
  • Natural key lookup for projects and issues
  • Retry-safe create routes with Idempotency-Key
  • Cursor pagination for large list routes

Overview

Quickstart sequence

Create a token, verify it, resolve workspace shape, and make your first predictable read and write calls.

Complete these steps

Run them in order.

  • Create a workspace token from Settings → Admin → Integrations.
  • Call GET /api/external to verify auth and read the workspace capability map.
  • Call /teams, /users, and /statuses before you create anything that depends on team, assignee, or status references.
  • Use project keys, issue keys, and Idempotency-Key headers so your automation remains readable and retry-safe.

Companion guides

Reference coverage and deeper client behavior.

API reference covers endpoint-by-endpoint browsing.

Developer guide covers retries, automation queues, pagination, caching, and structured recovery.

Webhook guide covers signatures, delivery semantics, event types, and receiver design.

Before you call Aurora

Prerequisites

Aurora's external API is designed for authenticated backend and automation clients. API routes and browser app routes are separate.

Important boundary

API tokens work on /api/external/* and can authenticate trusted MCP clients at /api/mcp. They do not create a browser session and cannot open protected app pages like /settings, /board, or /discussion.

Authentication

Create a token and send it correctly

A workspace token is the fastest way to start. Each token belongs to exactly one workspace and implicitly scopes every request to that workspace.

Create an API token

Generate it once, copy it once, and store it securely.

  1. 1. Sign in to Aurora WorkOS.
  2. 2. Open Settings → Admin → Integrations.
  3. 3. Enter a token name and create the token.
  4. 4. Copy the plaintext token immediately. Aurora only shows it once.

Workspace tokens currently begin with aurora_pat_.

Preferred authentication headers
Authorization: Bearer aurora_pat_your_token_here
Content-Type: application/json

Accepted header formats

Aurora prefers Authorization: Bearer ... but also accepts Authorization: Token ... and X-API-Key: ... for compatibility.

Validate the token

Make your first request against GET /api/external

Always start with the overview endpoint. It confirms the token, shows which workspace you are inside, and returns the endpoint map and capability flags for that workspace.

First cURL request
TOKEN="aurora_pat_your_token_here"

curl https://www.auroraworkos.com/api/external \
  -H "Authorization: Bearer $TOKEN"

What success looks like

A successful response tells you both where you are and what the token can do.

  • Workspace id, name, slug, and type
  • Token name and queue assignee id
  • Endpoint map for discovery, projects, issues, comments, and meetings
  • Capability flags such as cursorPagination, idempotencyKeys, and issueComments
Response shape to expect
{
  "ok": true,
  "token": {
    "name": "Codex automation",
    "assigneeId": "api-token:Codex automation"
  },
  "principal": {
    "kind": "api_token",
    "id": "api-token:Codex automation"
  },
  "workspace": {
    "id": "workspace-id",
    "name": "Workspace",
    "slug": "workspace"
  },
  "capabilities": {
    "humanCallerAuth": true,
    "cursorPagination": true,
    "idempotencyKeys": true,
    "structuredErrors": true,
    "issueComments": true,
    "meetings": true,
    "discussionVisibilityScoped": true
  }
}

Resolve the workspace first

Run discovery before you write

Aurora is intentionally discovery-first. That keeps client prompts, automation payloads, and retry behavior stable even when workspace shape changes over time.

StepPurpose
GET /api/externalValidate the token, read the capability map, and discover the current token queue identity.
GET /api/external/teamsResolve team ids and team keys before project or status work.
GET /api/external/usersResolve owners, reporters, human assignees, and automation queues.
GET /api/external/statusesLoad the valid statuses for the team you plan to operate on.

Concepts

Understand the core Aurora API concepts

These are the concepts that tend to trip integrations when they are not explicit in the docs.

ConceptWhat it means in Aurora
Workspace-scoped tokensEvery token belongs to one workspace. Reads and writes resolve only inside that workspace boundary.
Stable key lookupProjects and issues support by-key routes so operators and agents can work in natural identifiers instead of opaque ids.
Automation agentsAPI token names become assignable queue identities and are returned alongside human workspace members.
Project-linked agenda tagsAgenda tags inherit a linked meeting project when sourceProjectId is omitted; send an explicit null only when the tag should remain agenda-only.
Discussion visibilityStakeholder discussion groups are effective-user scoped; owners can keep a group browser-visible while hiding it from external API reads and writes.
JSON-only contractThe external API is JSON-based. Link-backed attachments are supported, while binary file transfer remains an app-session workflow.
Signed webhooksWebhook POSTs are best-effort triggers with raw-body HMAC signatures. They do not authorize the receiver to call Aurora.

Do something useful

First working workflows

Once discovery succeeds, the next most useful thing is usually a read, a retry-safe project create, and then an issue create or update that uses stable keys.

List projects
curl https://www.auroraworkos.com/api/external/projects \
  -H "Authorization: Bearer $TOKEN"
Create a project with Idempotency-Key
curl -X POST https://www.auroraworkos.com/api/external/projects \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: docs:project:weekly-scorecard" \
  -d '{
    "name": "Weekly Scorecard",
    "teamKey": "CORE"
  }'
Create an issue using project and team keys
curl -X POST https://www.auroraworkos.com/api/external/issues \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: docs:issue:weekly-scorecard-missed" \
  -d '{
    "title": "Weekly scorecard missed",
    "teamKey": "CORE",
    "projectKey": "SCORE",
    "statusKey": "todo"
  }'

Surface area

Endpoint families

Aurora's reference surface is intentionally compact but broad enough to support real execution workflows.

Discovery

Start every new client with discovery so you can resolve teams, statuses, users, and workspace capabilities before you mutate anything.

  • GET /api/external
  • GET /api/external/teams
  • GET /api/external/users
  • GET /api/external/statuses

Projects

Project routes support both opaque ids and stable key-based lookups so operators and agents can work in more human-readable terms.

  • GET /api/external/projects
  • GET /api/external/projects/{projectId}
  • GET /api/external/projects/by-key/{teamKey}/{projectKey}
  • POST /api/external/projects

Issues

Issue routes are designed for triage, automation queue pickup, and stable lookup by issue key or project key.

  • GET /api/external/issues
  • GET /api/external/issues/{issueId}
  • GET /api/external/issues/by-key/{issueKey}
  • POST /api/external/issues

Issue containers and milestones

Issue containers provide epic-like grouping, while container milestones model non-task checkpoints with owners, status, dates, tags, comments, and activity history.

  • GET /api/external/issue-containers
  • GET /api/external/issue-container-milestones
  • POST /api/external/issue-container-milestones
  • GET|PATCH|DELETE /api/external/issue-container-milestones/{milestoneId}

Issue comments

Comments are first-class external resources so human operators and automation can leave durable audit trails on the same issue thread.

  • GET /api/external/issues/{issueId}/comments
  • POST /api/external/issues/{issueId}/comments

Issue relationships, attachments, and sub-tasks

Issue utility routes cover mainline relationships, link-backed attachments, and lighter child work that remains under one parent issue.

  • POST|DELETE /api/external/issues/{issueId}/links
  • GET|POST /api/external/issues/{issueId}/attachments
  • GET|POST /api/external/issues/{issueId}/subtasks
  • GET|PATCH|DELETE /api/external/issues/{issueId}/subtasks/{subtaskId}

Meetings and agenda workflows

Aurora's external API also covers structured meeting execution so agenda capture and task conversion can stay inside the same automation boundary.

  • GET /api/external/meetings
  • POST /api/external/meetings
  • GET|PATCH|DELETE /api/external/meetings/{meetingId}
  • GET /api/external/meetings/settings

Stakeholder discussions

Discussion routes are scoped to the effective Aurora user and only expose groups the owner has left visible to external API clients.

  • GET|POST /api/external/discussion
  • PATCH /api/external/discussion/groups/{groupId}
  • GET|POST /api/external/discussion/topics
  • GET|PATCH /api/external/discussion/topics/{topicId}
Open the full API reference

Next step

Once the quickstart is working, move straight into the developer guide so your integration handles retries, pagination, automation queues, and structured recovery correctly the first time.