Jira

Hierarch syncs with Jira Cloud to bring issue tracking into the design workflow. Because Jira Cloud restricts browser CORS requests, all API traffic routes through a Vercel serverless proxy.

Architecture

Jira Cloud does not allow direct browser requests to its REST API due to CORS restrictions. Hierarch routes all Jira API traffic through a Vercel serverless function at /api/jira-proxy. The proxy forwards requests to the Jira REST API with the user's credentials and returns the response to the browser.

Browser (Hierarch)
  → POST /api/jira-proxy
    → Vercel Serverless Function
      → Jira Cloud REST API (yoursite.atlassian.net)
        ← Response
      ← Forwarded to browser

Authentication

The Jira integration uses Atlassian's 3-legged OAuth 2.0 (3LO) flow. When registering Hierarch in the Atlassian Developer Console:

Application Name	Hierarch
Application Type	Web Application
Redirect URI (prod)	https://hierarch.vercel.app/api/auth/callback/jira
Redirect URI (dev)	http://localhost:3000/api/auth/callback/jira
Authorization URL	https://auth.atlassian.com/authorize
Token URL	https://auth.atlassian.com/oauth/token

Required OAuth Scopes

read:jira-work	Read issues, projects, boards, sprints, and epics
write:jira-work	Create and update issues, transitions, comments
read:jira-user	Read user profiles and avatars
read:me	Read the authenticated user's profile

Hierarch requests the minimum set of scopes needed. Additional scopes are added only when new integration features require them.

API Endpoints

Hierarch uses the Jira REST API v3 through the serverless proxy. All endpoints target https://yoursite.atlassian.net/rest/api/3/.

Endpoint	Method	Purpose
/rest/api/3/search	POST	Search issues using JQL (primary issue list query)
/rest/api/3/issue/{key}	GET	Fetch a single issue with all fields
/rest/api/3/issue/{key}	PUT	Update issue fields (summary, description, status)
/rest/api/3/issue	POST	Create a new issue
/rest/api/3/status	GET	List all statuses in the project
/rest/api/3/issue/{key}/transitions	GET	List available transitions for an issue
/rest/api/3/issue/{key}/transitions	POST	Transition an issue to a new status
/rest/api/3/myself	GET	Fetch the authenticated user's profile

Data Hierarch Reads

Authenticated user profile
Issues matching a JQL query (key, summary, description, status, priority, assignee, labels, dates)
Available transitions for each issue
Project statuses

Data Hierarch Writes

New issues (summary, description, project, issue type, priority)
Issue field updates (summary, description)
Status transitions (moving issues through workflow)

Hierarch does not modify project settings, workflows, custom fields, or any configuration-level data.

Serverless Proxy

The proxy function deploys as a Vercel serverless function. It handles:

Receiving the target Jira endpoint path and method from the client
Constructing the full Jira URL from the user's site URL
Attaching the OAuth Bearer token in the Authorization header
Forwarding the request body for POST/PUT operations
Returning the Jira response with appropriate CORS headers

Proxy Request Format

POST /api/jira-proxy
Content-Type: application/json

{
  "site": "yoursite.atlassian.net",
  "path": "/rest/api/3/search",
  "method": "POST",
  "body": {
    "jql": "project = DESIGN AND status != Done",
    "maxResults": 50
  }
}