# Step 1: Connect an Attio workspace

Every other setting depends on this one, because the app cannot list your record types or attributes until it can talk to your workspace. The key is per project, so connecting one project leaves every other project untouched.

There is no separate Test button during first-time setup. Pressing Next is what tests the key, stores it and moves you on.

## Before you start

Create the key in Attio under Workspace settings, then Developers. The key needs two permissions, and the app names them exactly as Attio does.

| **Attio permission**       | **Why the card needs it**                                                    |
| -------------------------- | ---------------------------------------------------------------------------- |
| record\_permission:read    | Read the record that matches the reporter, and the values on it              |
| object\_configuration:read | List your record types and their attributes, so you can choose which to show |

## Connect the project

* Open the Jira project, then Project settings, Apps, Attio.
* Paste the whole key into the key field. An Attio workspace key is exactly 64 characters.
* Press Next. The app asks Attio to identify the key before it stores anything.
* Check the workspace name in the green confirmation. That name is the proof the key belongs to the workspace you meant, rather than another one you also have a key for.

ℹ️

**Nothing is stored until the test passes.** A key that Attio rejects is never written to storage, so a failed attempt cannot leave a half-connected project behind.

## When the key is refused

| **What the screen says**                                                                                                                   | **What it means**                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| Attio did not accept that API key. Check the whole key was pasted, with no spaces.                                                         | Usually a truncated paste. Copy the key again from Attio.                                                            |
| Attio rejected that API key. It may have been revoked, or it may belong to a different workspace.                                          | The key is well formed but no longer valid. Create a new key in Attio under Workspace settings, Developers.          |
| That key is valid but cannot read records. Add record\_permission:read and object\_configuration:read to it in Attio, then paste it again. | The key works, but the two reads above were never granted. Edit that same key in Attio rather than making a new one. |
| Attio returned no objects for this key. That usually means the key belongs to a workspace that has not been set up yet.                    | The key is fine, but the workspace has no record types to choose from.                                               |
| Attio is rate limiting this workspace. Try again shortly.                                                                                  | Attio asked the app to slow down. The app retries once on its own before showing this.                               |

## Testing a connection later

Once setup is finished the wizard becomes a row of tabs, and the Connection tab gains a test you can run at any time. Running it with the key field left empty re-tests the key the project already has, which answers "is this connection still working" without anyone needing to find the key again.

---

## A few things worth knowing

* An empty key field means keep the key this project already has. Saving other settings never clears a stored key, and the only way to remove one is Reset to defaults.
* Connecting a key does not switch the card on. It is the first of six steps, and the card appears only once a record type, a matching attribute, at least one field and a placement are all chosen.
* The confirmation holds for about a second and a half before step 2 arrives, which is deliberate: it is your only chance to read the workspace name.

---

## Related

[Step 2: Choose the record type](https://help.gocapable.com/attio-for-jira/step-2-choose-the-record-type.html)

[Create an Attio API key](https://help.gocapable.com/attio-for-jira/create-an-attio-api-key.html)

[Attio rejected this key](https://help.gocapable.com/attio-for-jira/attio-rejected-this-key.html)

---

_One key, one project, one workspace._