> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clipstake.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces, projects, and teams

> How ClipStake scopes keys, data, and the people who can change them.

## Workspace

A workspace is the whole account: its members, projects, connected Instagram
accounts, API keys, and billing. Every key belongs to a workspace and reaches
everything in it.

A person belongs to one workspace. There is no workspace switcher.

## Project

A project groups tracked media inside a workspace. Every submission operation
names one with `project_id`.

```bash theme={null}
curl "https://api.clipstake.com/v1/projects" \
  --header "Authorization: Bearer $CLIPSTAKE_API_KEY"
```

Projects separate media, not people and not access. Every member of a workspace
sees every project, and a workspace key reaches every project.

Two projects can track the same media. They are separate sets of tracked media,
which is what a project is for.

<Note>
  Connected Instagram accounts belong to the workspace, not to a project. A
  connection minted from one project is reachable from all of them.
</Note>

Projects are created, archived, and restored in the Console. There is no
project lifecycle endpoint in the API. `GET /projects` is discovery, so your
code can resolve a `project_id` without one being pasted into it.

Archiving a project stops its media and keeps every row. Restoring brings the
project back and leaves its media stopped, so nothing restarts your bill
without you asking.

## API keys

Keys belong to the workspace. They reach every project, survive the person who
created them leaving, and are revoked explicitly in the Console.

The full key is shown once, at creation. ClipStake stores a hash, so a key can
be listed by its prefix and last four characters but never shown again. Create
a new key and revoke the old one when you need to rotate.

## Roles

Roles are enforced on the server, not only in the Console.

| Role      | Read data | Operate product | Billing | Manage members                          |
| --------- | --------- | --------------- | ------- | --------------------------------------- |
| Owner     | Yes       | Yes             | Yes     | Yes, including transferring ownership   |
| Admin     | Yes       | Yes             | Yes     | Yes, except anything involving an Owner |
| Developer | Yes       | Yes             | No      | No                                      |
| Viewer    | Yes       | No              | No      | No                                      |
| Billing   | Yes       | No              | Yes     | No                                      |

"Operate product" covers projects, connections, tracked media, and creating,
listing, and revoking workspace keys, whoever created them.

A workspace always has exactly one Owner. Making another member Owner is a
transfer, confirmed in a dialog, and the previous Owner becomes an Admin. A
sole Owner transfers ownership before leaving.

## Identity in your own code

| Id                 | Whose it is | Use it for                                   |
| ------------------ | ----------- | -------------------------------------------- |
| `project_id`       | ClipStake   | Naming the project in submission operations. |
| `external_user_id` | Yours       | Your id for an end user. Opaque to us.       |
| `username`         | Instagram   | Addressing a connected account.              |
| `shortcode`        | Instagram   | Addressing a tracked media.                  |

Handle lookup is case insensitive. Usernames change, so store your own
`external_user_id` as the durable reference to a person and treat the handle as
a display value.