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

# App Visibility

> Control who can access your apps with public, private, and privileged modes.

Every app exposed through Rigbox has a **visibility mode** that determines who can access it. By default, apps are private - only you can see them. You can open them up to the world or share them with specific people.

## Visibility Modes

There are three visibility modes:

| Mode           | Who can access                   | Use case                                        |
| -------------- | -------------------------------- | ----------------------------------------------- |
| **Private**    | Only the workspace owner         | Development, testing, internal tools            |
| **Public**     | Anyone with the URL              | Demos, public APIs, static sites, documentation |
| **Privileged** | Owner + specific email addresses | Team collaboration, client previews, staging    |

<Note>
  Private is the default for all newly created apps. You must explicitly change the visibility to make an app accessible to others.
</Note>

## How Access is Enforced

When a request arrives at an app subdomain (e.g., `<APP_NAME>.rigbox.dev`), Rigbox checks the visibility mode before forwarding the request to your service:

* **Public**: the request is forwarded immediately with no authentication check.
* **Private**: the request must include valid authentication matching the workspace owner. Unauthenticated requests receive a 403 response.
* **Privileged**: the request must include valid authentication for either the workspace owner or a user whose email is in the `allowed_emails` list.

<Tip>
  CORS preflight requests (`OPTIONS` method) are always allowed through regardless of visibility mode. This ensures browser-based applications can function correctly even when the app is private or privileged.
</Tip>

## Setting Visibility

Use `rig app share` to change an app's access mode. Pick exactly one mode per call: `--public`, `--private`, or `--emails`.

### Make an App Public

```bash theme={null}
rig app share --app $APP --public
```

The `--app` value can be an app id, name, or subdomain.

See [Update Visibility](/api-reference/apps/update-visibility) for the full request/response schema.

### Make an App Private

```bash theme={null}
rig app share --app $APP --private
```

### Share with Specific People (Privileged)

Privileged mode lets you grant access to specific email addresses. This is useful for sharing a staging environment with teammates or showing a client preview. Passing `--emails` implies allowlist (privileged) visibility.

```bash theme={null}
rig app share --app $APP --emails alice@example.com,bob@example.com
```

<Warning>
  The `--emails` allowlist only applies in privileged mode. Switching the app to `--public` or `--private` clears it.
</Warning>

## Updating the Allowed Emails List

To add or remove people from the privileged access list, run `rig app share --emails` again with the complete list. The list is replaced entirely - it's not additive.

```bash theme={null}
# Add carol to the existing list
rig app share --app $APP \
  --emails alice@example.com,bob@example.com,carol@example.com
```

<Note>
  To remove someone, run the command again without their email. There is no separate "remove" command - you always send the full list.
</Note>

## Checking Current Visibility

Retrieve the app details to see its current visibility mode and allowed emails.

```bash theme={null}
rig app ls --query "[].{name: name, visibility: visibility, allowed_emails: allowed_emails}"
```

`rig app ls` lists your apps with their current visibility; use `--query` to narrow the output to the fields you care about.

See [Get App](/api-reference/apps/get) for the full response schema.

## Complete Example: Development to Production

This walkthrough shows a typical flow - develop privately, test with teammates, then go public.

### Deploy your app privately

Create and expose your app. It starts as private by default.

```bash theme={null}
# Expose port 3000 (private by default)
rig app expose-port --workspace $WORKSPACE --port 3000 --wrap
```

The app is now reachable at `https://<APP_NAME>.rigbox.dev`, but only to you.

### Test and iterate

While the app is private, only you can access it. Make changes, test, and refine.

### Share with your team for review

Once you're ready for feedback, switch to privileged mode.

```bash theme={null}
rig app share --app $APP \
  --emails teammate@company.com,reviewer@company.com
```

### Go public

After the team approves, make it available to everyone.

```bash theme={null}
rig app share --app $APP --public
```

### Lock it back down if needed

You can revert to private at any time.

```bash theme={null}
rig app share --app $APP --private
```

## Authenticating Requests to Private Apps

When your app is private or privileged, requests from outside the workspace need an `X-Rigbox-Key` header to get through. Use any of your API keys (`rb_*`) as the value. You can create and manage keys on the **Settings > API Tokens** page in the dashboard.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://<APP_NAME>.rigbox.dev/data \
    -H "X-Rigbox-Key: $RIGBOX_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://<APP_NAME>.rigbox.dev/data",
      headers={"X-Rigbox-Key": api_key},
  )
  print(response.json())
  ```
</CodeGroup>

<Tip>
  The **Usage** tab on the app detail page includes this header automatically in its copy-paste examples when the app is private. No need to remember the header name yourself.
</Tip>

<Note>
  This header is only needed for requests arriving from the public internet. Services running inside the same workspace can call each other on `localhost` without any auth header.
</Note>

## Security Considerations

* **Private apps are not accessible without authentication.** Even if someone knows the subdomain URL, they cannot access a private app.
* **Privileged mode uses email verification.** Users in the `allowed_emails` list must authenticate through Rigbox to access the app.
* **Public apps are open to the entire internet.** Only set an app to public if you intend for anyone to access it. Don't expose admin panels, databases, or sensitive services as public.
* **Visibility changes take effect immediately.** There is no propagation delay - the next request will use the new visibility mode.

<Warning>
  Be careful with public visibility for apps that expose sensitive interfaces (e.g., database clients, admin panels, file browsers). Consider using privileged mode with specific emails instead.
</Warning>

## Next Steps

* [Expose Ports & Route Apps](/guides/expose-and-route) - create and manage app routes
* [Workspaces](/guides/workspaces) - workspace lifecycle management
* [Catalog Apps](/guides/catalog) - install pre-packaged apps with routing handled automatically