Setup

1. Create or sign into your Jira account

2. Generate an API token

Go to Atlassian API tokens
Click "Create API token"
Give your token a label (e.g., "Hyphen Integration")
Copy the generated token - you'll need it in the next step

3. Get your Cloud ID and Organization ID

Go to Atlassian Home
After logging in, check your browser's URL bar
Your Organization ID can be found in the URL:
https://home.atlassian.com/o/[your-org-id]
Your Cloud ID can be found in your Jira instance URL:
https://[your-cloud-id].atlassian.net

4. Connect Jira

Enter your API token and IDs below to complete the integration.

Configuration

Field	Type	Description
`cloudId`	`string` (required)	JIRA cloud ID provided by the user, used for future requests.
`email`	`string` (required)	JIRA admin email provided by the user, used for reference and to authenticate future requests.
`organizationId`	`string` (required)	Atlassian organization ID provided by the user, used for reference and future requests.
`apiToken`	`string` (required)	Secret Atlassian API Token provided by the user. Encrypted and stored as `encryptedToken`.
`secrets`	`object`	Built during integration config setup containing:
`encryptedToken`	`string`	Encrypted `apiToken` used to authenticate future requests.
`accountId`	`string`	JIRA admin account ID, used for reference and display.

Connections

User

User connections can only connect to existing Users in JIRA. If a connection is created without providing input to connect to an existing User, the member email will be used to try and find the existing User.

Configuration

Field	Type	Description
`userId`	`string`	JIRA user account ID.
`email`	`string`	JIRA user email address or Hyphen member email.
`displayName`	`string`	Display name of the JIRA user.

Connection Input

Provide the JIRA email to connect to an existing User.

Verification

No verification needed if the user's public email matches the member’s email.
If the emails don't match, a verification email will be sent to the JIRA user's email.

Permission Group

Permission Group Connections can connect to existing Groups in JIRA or one will be created if no connection input is provided.

When creating a new group in JIRA, the Hyphen team name will be used as the group name.

Configuration

Field	Type	Description
`organizationId`	`string`	`organizationId` from the integration configuration.
`groupName`	`string`	Group name in JIRA used for display.
`groupId`	`number`	Unique group ID in JIRA.

Connection Input

Provide the JIRA group name to connect to an existing Group.

Verification

Existing groups will be verified by the organization admin who set the email in the integration config.

Access

A User connection will be added as a member when added to the group.

Project Board

Project Board Connections can connect to existing Project Boards in JIRA or one will be created if no connection input is provided.

When creating a new project board, the Hyphen App or Project name will be used as the project board name. The name will be converted to uppercase, spaces and hyphens will be removed, and only the first ten characters will be used.

Configuration

Field	Type	Description
`projectId`	`string`	Unique code project board ID in JIRA.
`projectKey`	`string`	Unique code project board key in JIRA.
`orgSlug`	`string`	`githubOrgName` from the integration configuration.
`projectName`	`string`	Project board name in JIRA, used for display and reference.

Connection Input

Provide the JIRA project board name to connect to an existing Project Board.

Verification

A verification email will be sent to the lead email to verify the existing project board.

Access

A Team connection will be added with a "Member" role when added to the project board.