Admin setup

Namespaces, sources, keys and roles, set up before the pilot starts.

What you need

• The Owner or Admin role in Workstate.
• For GitHub: someone who can install a GitHub App on your organization. That's an organization admin, or the owner of a personal account.
• For Confluence and Jira: a Cloud site on atlassian.net, the email address of the Atlassian account that Workstate will read as, and an Atlassian API token for that account.
• Your namespace plan from the launch strategy.

1. Plan namespaces by team and sensitivity

A namespace is a separate index with its own sources, search and ledger. Everyone with access to a namespace sees everything in it, so split namespaces by who may see the content.

Namespace (for example)	What goes in it	Who needs it
Engineering	Product repositories, engineering Confluence spaces and Jira projects	Engineering and operations
Support	The support Jira project and the help center space	Support and engineering leads
Handbook	The employee handbook and policies	Everyone who asks HR questions
Legal	Policies and contracts	Legal only

Don't split where teams need each other's context. Agents in different namespaces can't see each other's ledger, so engineering and operations usually share one.

2. Create the namespaces

1. Open Namespaces.
2. Enter a name, then select Create. The console switches to the new namespace.
3. Note the namespace's id, which starts with ws-. Agents send it in the X-RAG-Namespace header.

Everyone who is an owner or admin when a namespace is created is given it. Anyone else reaches it only once an owner or admin gives it to them, as in step 8.

3. Connect sources in each namespace

Select the namespace in the switcher at the top of the console's sidebar, open Sources, and choose a tile under Add a source. The Sources page shows only the selected namespace's sources.

• GitHub. Install the Workstate GitHub App, and choose repositories on GitHub's own install page. Workstate reads each repository's default branch, read-only. Workstate doesn't filter committed secrets, so remove them first. If you later stop sharing a repository with the App, Workstate removes it from the index at the next sync.
• Confluence and Jira. Enter a name, the site, the space or project keys (up to 50), the account email and the API token. Workstate checks them against the site before it saves the source, and stores the token encrypted. Workstate reads as that account, so use one that can see only what this namespace may show.
• Upload files. Enter a name, choose whether Each top-level folder is a repository (you can't change this later), and select Create source. Then add files on the source's page. Text and code files can be up to 1 MB each. PDF, Word, Excel and PowerPoint files can be up to 50 MiB each. A source holds up to 2 GiB and 20,000 files. Uploads refuse private keys and .env files.

A source's name becomes the repository name that search filters use. For example, a source named "Support tickets" appears as support-tickets.

4. Set sync schedules

New GitHub, Confluence and Jira sources sync once a day. On a source's page, an owner or admin can change that to every 5 minutes, 15 minutes, 1 hour, 6 hours, 1 day or 1 week. Upload sources sync when files are uploaded.

Anyone can select Sync now. Only owners and admins can pause, resume, cancel or delete a source. Deleting a source removes everything indexed from it, and its files and history.

5. Check that search works

In each namespace, open Search and ask a question you already know the answer to. Check that:

• the documents you expect appear, under the repository names you expect;
• the Code, Wiki and Ledger filters narrow the results as expected. Wiki holds documents: Confluence pages, Jira issues and uploaded documents;
• each source's Sync history shows no warning you need to act on, such as a scanned document with no text.

6. Decide who gets which role

Action	Owner	Admin	Member
Search, read and write the ledger, create your own keys	Yes	Yes	Yes
Select Sync now	Yes	Yes	Yes
Add, change, pause or delete sources, and upload files	Yes	Yes	No
Create or delete namespaces	Yes	Yes	No
Invite people	Yes, as any role	Yes, as a Member or Admin	No
Give or take away someone's namespace access	Yes, except your own	Yes, except an owner's or your own	No
Revoke another person's keys	Yes	Yes, except an owner's	No

Keep admins few. An admin can delete sources and namespaces, and is given every new namespace. Owners and admins can give only the namespaces they hold. A person's role is set in their invitation and can't be changed afterwards, so choose it with care.

7. Prepare keys and agent config

Each person creates their own keys. Nobody can create a key for someone else.

1. On API keys, in the Create a key panel, enter a label that says where the key is used, such as "claude-code on the laptop". Select Create key. The key is shown once.
2. Set the key as RAG_API_KEY in the environment where the agent runs.
3. With the namespace selected in the switcher, copy the config under Connect your agent into the project's .mcp.json. It connects to that namespace only. If the server names end in the namespace id, rename them to rag-corpus and rag-ledger, the names the agent instructions use. See Server names.

Keys don't expire and have no scopes: a key reaches every namespace its person can reach. Each person can hold up to 25 live keys. One key for each machine or agent lets you revoke one without stopping the rest. See API keys.

8. Invite the pilot team

1. Open Team and select Invite. The Invite a teammate dialog opens.
2. Enter the person's Email. It must be an address that GitHub has verified for their account.
3. Choose a Role: your own or one below it.
4. Under Namespaces, select the ones the person needs. Only namespaces you hold are listed. For a Member, the namespace you're viewing is selected at first. For an Admin or Owner, all of yours are, since they're given every new namespace anyway. Changing the role resets the selection, so choose the role first.
5. Select Invite. With no namespace selected, the dialog warns that the person will reach nothing until someone gives them one, but you can still invite them.
6. Tell them yourself: no email is sent. They sign in to the console with Continue with GitHub, using a GitHub account that has that address as a verified email. From their first request, they reach the namespaces in their invitation.

Change someone's namespaces later

The Namespaces column on the Team page shows which of your namespaces each person reaches. To change it, open the picker in their row. Select a namespace to give it to them, or select a ticked one to take it away. Each change applies at once, from the person's next request.

• The picker lists only the namespaces you hold, and you can give only those.
• Nobody can change their own access. Ask another owner or admin.
• Only an owner can change an owner's access.

Invitations made before namespaces could be chosen

Invitations made before the invite dialog had a Namespaces field carry no namespaces, and neither do the seats that accepted them. If someone invited then can't reach what they need, give them their namespaces in the Namespaces column.

Check it worked

• Every namespace in your plan exists, and you've noted its id.
• Every source is in the right namespace, and has synced at least once.
• No connected repository contains committed secrets.
• Each Atlassian account sees only what its namespace may show.
• No source is failing. In each namespace, the Overview page's Source health panel lists its sources with their last successful sync.
• A search check passed in each namespace.
• Only the people who need it hold the Admin role.
• Each invited person's row on Team shows the role and namespaces they need, and the welcome message from the onboarding kit is ready.

Troubleshooting

Problem	What to check
The tiles under Add a source show "Only owners and admins can add sources"	You have the Member role. Ask an owner or admin.
A Confluence or Jira source won't save	The site must end in .atlassian.net, and the email and token must belong to the same account.
A source shows as failed	Open it: the error is on its page. If the Atlassian token was revoked, use Replace token on the source's page.
An upload refused some files	The upload lists each refused file with its reason, such as its type or size.
Search returns nothing	Check which namespace is selected, that the source has synced, and which filter is on.
An invited person sees No namespace yet	Nobody has given them a namespace. Give them one in the Namespaces column on Team.

Next steps

• Designing use cases
• Onboarding kit
• Roles