> ## Documentation Index
> Fetch the complete documentation index at: https://resources.athenaintel.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect Zephyr Enterprise to Athena: Test Cases, Executions, and Setup
> Zephyr Enterprise setup covers your API token, connecting an instance, test case and execution reads, approval-gated writes, and troubleshooting.
Connect Zephyr Enterprise to Athena so each member can browse test
repositories, read test cases and their steps, search with ZQL, review test
cycles and executions, record test results and create test cases as their
**own Zephyr user**. Your Zephyr role and project assignments apply unchanged.
Athena sees exactly what you can see in Zephyr, nothing is shared through an
integration user, and every result Athena records or test case it creates is
attributed to you.
Zephyr Enterprise has no sign-in flow Athena can use, so each member
connects with an **API token** they create in Zephyr (Zephyr Enterprise 6.6
and later). Nothing needs to be registered for your workspace first: the
**Zephyr Enterprise** card is available to every member.
## Step 1: Create an API token in Zephyr (each member)
1. Sign in to Zephyr Enterprise.
2. Open the menu at the top right and choose **API Token**.
3. Click **Create**, give the token a label you will recognize (for example
`Athena`), and copy it. Zephyr shows the token only once.
A Zephyr API token does not expire. It works until you delete it in Zephyr,
and it can do whatever your Zephyr user can do.
## Step 2: Connect your instance in Olympus (each member)
1. Navigate to
**[Integrations](https://app.athenaintel.com/dashboard/integrations/)** and
click **Connect Zephyr Enterprise** on the **Zephyr Enterprise** card,
under **Project Management & Ticketing**.
2. Enter your instance's address: the one you open Zephyr at, such as
`https://acme.yourzephyr.com`, or your company's own server with its port
and path, such as `https://zephyr.acme.com:8443/zephyr`. A link copied from
Zephyr works too.
3. Paste the API token and click **Connect**. Athena asks Zephyr whose token
it is and confirms the connection with your Zephyr user.
To connect another instance, or another Zephyr user, click **Connect another
Zephyr Enterprise instance**.
Athena connects only over https, and only to an instance reachable from the
internet. An instance inside a private network cannot be connected. If your
server accepts traffic only from allowlisted IP addresses, ask Athena
Intelligence for Athena's outbound addresses.
## What Athena can do
Once connected, the **Zephyr Enterprise toolkit** gives agents these tools.
| Tool | What it does | Approval |
| - | - | - |
| List Zephyr Enterprise Connections | Lists your connected instances and the Zephyr user each uses | No |
| List Zephyr Projects | Lists the projects you are assigned to | No |
| List Zephyr Releases | Lists a project's releases and their dates | No |
| Browse Zephyr Test Repository | Lists a release's folders and the test cases in a folder | No |
| Get Zephyr Test Case | Reads a test case with its steps, test data and expected results | No |
| Search Zephyr | Searches a release's test cases, executions or requirements with words or ZQL | No |
| List Zephyr Test Cycles | Lists a release's test cycles and their phases | No |
| List Zephyr Executions | Lists the executions of a cycle phase or release, optionally only yours | No |
| Update Zephyr Executions | Records the status and notes of up to 50 executions | **Yes**, every time |
| Create Zephyr Test Case | Creates a test case with its steps in a test repository folder | **Yes**, every time |
A few behaviors to know:
* **Plain-language requests work.** Ask "which tests failed in the 2.4
regression cycle" or "add a login test case to the Authentication folder".
Athena finds the project, release, folder or cycle first.
* **Everything lives in a release.** Test repositories, cycles and searches
are scoped to a release, so Athena lists a project's releases when you
don't name one. Large lists come back a page at a time, and Athena reads
further pages only when it needs them.
* **Statuses and priorities come from your instance.** Athena checks a status
(Pass, Fail, WIP, Blocked, or your own) or a priority against your
instance's own list before writing, and nothing changes if it is not on it.
If Athena cannot read that list, it writes nothing rather than guess, since
an administrator can renumber statuses and priorities.
* **Results are read back.** After recording results, Athena reads each
execution again and reports what Zephyr now holds. Notes you don't change
stay as they are; if your Zephyr version does not let Athena read an
execution's notes, Athena asks for the notes instead of overwriting them. A
result is recorded under your Zephyr user.
* **New test cases land where you approve.** Athena creates the test case in
the folder you approved, with its steps in order. If Zephyr refuses a step
after the test case exists, Athena says which steps were added.
* **Several instances.** With more than one instance connected, name the
instance you mean. Athena can list your connections.
* **Reads need no approval.** Read tools run without a prompt in chat and in
scheduled agent runs that act as you. Write tools are available only in
chat, where you can approve them. An automation's own identity holds no
Zephyr connection, so automation steps cannot call Zephyr.
## Use Zephyr Enterprise from a computer
On a computer with your Zephyr Enterprise connection attached under
**Connected Catalogs**:
* `ZEPHYR_BASE_URL` holds your instance's address.
* `ZEPHYR_API_URL` holds its REST API root,
`/flex/services/rest/latest`.
* `athena-catalog-token zephyr_enterprise_direct` prints your API token.
```bash theme={null}
curl -H "Authorization: Bearer $(athena-catalog-token zephyr_enterprise_direct)" \
"$ZEPHYR_API_URL/user/current"
```
With more than one instance attached, `ZEPHYR_BASE_URL` and `ZEPHYR_API_URL`
describe the first one. For another instance, pass its catalog's asset ID to
`athena-catalog-token` and call that instance's own REST root.
The computer acts as you, and the token it receives is your long-lived Zephyr
API token. Attach your connection only to a computer you don't share, and
delete the token in Zephyr if it may have been copied.
## Token lifecycle & troubleshooting
* **Everything is per-user.** Results always reflect *your* Zephyr access,
and every change is attributed to you.
* **"Your Zephyr Enterprise connection no longer works."** Zephyr refused the
token: it was deleted, or your Zephyr user was disabled. Create a new token
in Zephyr and connect it again from the Integrations page.
* **"No Zephyr Enterprise REST API answered."** The address is not your
instance's. Use the address you open Zephyr at.
* **"Could not reach Zephyr Enterprise."** The instance is not reachable from
the internet, or a firewall blocks Athena. Ask your Zephyr administrator.
* **An http address is refused.** Athena sends your token over https only.
* **"Zephyr Enterprise did not share its list of execution statuses."** Your
Zephyr role may not be allowed to read the list, so Athena recorded nothing.
Try again, and if it keeps happening, ask your Zephyr administrator. A test
case can still be created without a priority.
* **"Does not share an execution's current notes."** Your Zephyr version
replaces notes when a result is recorded and does not let Athena read them
first. Give the notes to keep (or ask Athena to clear them) and try again.
* **Rate limits.** When Zephyr throttles requests, Athena says how long to
wait instead of retrying in a loop.
## Disconnecting
Open the Zephyr Enterprise connection in Athena and click **Disconnect**.
Athena deletes the API token it stored. The token itself stays valid in Zephyr
until you delete it there (the menu at the top right → **API Token**). Other
instances you connected stay connected.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.