# Permissions (/docs/guides/permissions)

Access in AISquare depends on three things together: a publication's visibility,
the user's authentication, and the user's role or membership. Not all data is
visible to all users, so your app should check access before fetching protected
content.

## Publication visibility [#publication-visibility]

Every AI Studio (publication) carries a visibility setting.

| Type      | Access                                   |
| --------- | ---------------------------------------- |
| `PUBLIC`  | Anyone, no authentication required       |
| `TEAM`    | Authenticated workspace members          |
| `PRIVATE` | Authenticated users with explicit access |

In short: public content is open, team content requires workspace membership,
and private content requires explicit access.

## Permission check [#permission-check]

AISquare exposes an endpoint that validates whether a user can access a
publication.

```text
POST /aistudios/permission/
```

```json title="Request"
{
  "url": "ai-research-studio"
}
```

It resolves the publication from the `url`, checks the user's membership and
roles, and may set a workspace context for subsequent requests.

### How access is resolved [#how-access-is-resolved]

1. Resolve the publication from the `url`.
2. Check its visibility.
3. Check authentication.
4. Check membership or role.
5. Grant or deny.

| Status | Meaning                                |
| ------ | -------------------------------------- |
| `200`  | Access granted                         |
| `401`  | Authentication required                |
| `404`  | Publication not found or access denied |

<Callout type="warn" title="404 can mean access denied">
  For non-public resources, a `404` may mean the user is not allowed to see the
  publication rather than that it does not exist. Do not assume `404` always
  means missing data.
</Callout>

### Workspace context [#workspace-context]

When access is granted, AISquare may set a workspace context (a cookie) so
later requests are scoped to the right workspace. Send it along on subsequent
calls to keep behavior consistent.

## Roles and membership [#roles-and-membership]

A user can hold different roles within a publication:

* **Creator.** The owner.
* **Co-creator.** An editor, reviewer, or other collaborator.
* **Workspace member.** A member of the workspace.

Roles determine whether a user can view content, edit or manage resources, and
see metrics and analytics. See [Studios](/docs/studios/overview) for how
creators and co-creators are managed.

## Access patterns [#access-patterns]

Public content needs no check:

```text
user  ->  request  ->  public data returned
```

Restricted content goes through authentication and a permission check first:

```text
user  ->  authenticate  ->  permission check  ->  access granted
```

## Best practices [#best-practices]

* **Check before you fetch.** Call the permission endpoint before requesting
  protected data.
* **Handle failures.** On `401`, prompt login; on `404`, show not found or
  restricted. See [Errors](/docs/reference/errors).
* **Cache results.** Avoid repeating the same check for the same user and
  publication.
* **Do not assume access.** Not every user can see every publication.

## Common mistakes [#common-mistakes]

* **Skipping the check.** Leads to surprise failures on later calls.
* **Treating 404 as missing.** It can mean access denied.
* **Ignoring workspace context.** Dropping the cookie causes inconsistent
  behavior across requests.

## Putting it together [#putting-it-together]

1. The user selects a studio.
2. Your backend checks permission.
3. If allowed, fetch the data.
4. If denied, handle the error.

## Next steps [#next-steps]

<Cards>
  <Card title="Authentication" href="/docs/getting-started/authentication" description="Set up credentials for permission checks." />

  <Card title="Core Concepts" href="/docs/getting-started/core-concepts" description="The entity visibility model." />

  <Card title="Studios" href="/docs/studios/overview" description="Publication-scoped endpoints and creator roles." />

  <Card title="Errors" href="/docs/reference/errors" description="Understand 401, 403, and 404 responses." />
</Cards>