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.

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 only work on /api/external/* routes. 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
  }
}

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.
JSON-only contractThe external API is JSON-based and does not create browser sessions or expose internal app routes.

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 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

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
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.