Skip to content

Commit f5073e9

Browse files
TizianoTTizianoT
committed
chore(docs): restructure security docs and enhance API Keys documentation
Separated Users and Roles & Privileges into dedicated pages for better organization. Completely rewrote API Keys documentation with detailed instructions for creating, managing, and using API keys. Cleaned up navigation structure and removed duplicate content.
1 parent 0345195 commit f5073e9

File tree

6 files changed

+325
-23
lines changed

6 files changed

+325
-23
lines changed

‎sqlite-cloud/_nav.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -287,7 +287,8 @@ const sidebarNav: SidebarNavStruct = [
287287
{ title: "Webhooks", filePath: "webhooks", type: "inner", level: 0 },
288288
{ title: "Pub/Sub", filePath: "pub-sub", type: "inner", level: 0 },
289289
//{ title: "Vector", filePath: "vector", type: "inner", level: 0 },
290-
{ title: "Users and Roles", filePath: "security", type: "inner", level: 0 },
290+
{ title: "Users", filePath: "users", type: "inner", level: 0 },
291+
{ title: "Roles & Privileges", filePath: "roles", type: "inner", level: 0 },
291292
{ title: "API Keys", filePath: "apikey", type: "inner", level: 0 },
292293
{ title: "Row-Level Security", filePath: "rls", type: "inner", level: 0 },
293294
{ title: "OffSync", filePath: "offsync", type: "inner", level: 0 },

‎sqlite-cloud/platform/apikey.mdx‎

Lines changed: 61 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,75 @@
11
---
22
title: Security and Access Control
3-
description: SQLite Cloud provides secure access to resources through role-based authorization, which ensures user isolation and enhances security and manageability.
3+
description: Manage API Keys for secure application access, server-to-server communication, and SDK integration.
44
category: platform
55
status: publish
66
slug: apikey
77
---
88

9-
## API KEYs
109

1110
API KEYs can be used as an alternative authentication mechanism.
1211
Authentication through API keys ensures the same privileges as the user to which they are associated.
1312
API KEYs are recommended for all server-to-server authentication cases and are necessary for using the REST APIs and the SDKs that uses the WebSocket APIs.
1413

15-
To create an API key for a user, click on the **Create API KEY** button.
14+
You can manage all keys in your cluster via the SQLite Cloud Dashboard under the **API Keys** section.
1615

17-
![Dashboard Create APIKEY](@docs-website-assets/introduction/dashboard_create_apikey.png)
16+
---
17+
18+
## Creating an API Key
19+
20+
You can create an API Key and immediately assign it to any existing user in your cluster.
21+
22+
1. Navigate to the **API Keys** section in the left sidebar.
23+
2. Click the **Create API Key** button.
24+
3. **API Key Name:** Enter a descriptive name to identify the key (e.g., `MobileApp_Prod`, `Backend_Worker`).
25+
4. **User:** Select the user this key will impersonate from the dropdown list.
26+
5. **Expiration:**
27+
* Select **Never expires** for long-running services.
28+
* Select **Set expiration date** to enforce a rotation policy or for temporary access tokens.
29+
6. Click **Create**.
30+
31+
[VIDEO: create_apikey_global.mp4]
32+
{/* <!-- Video showing the global creation flow: entering a name, selecting a user from the dropdown, picking a date, and creating --> */}
33+
34+
---
35+
36+
## Managing API Keys
37+
38+
The API Keys list provides a centralized view of all active keys, their associated users, and expiration status.
39+
40+
### Regenerating a Key
41+
If a key is lost, forgotten, or you suspect it has been compromised (leaked), you should regenerate it immediately.
42+
43+
1. Find the key in the list.
44+
2. Click the context menu (three dots) on the right.
45+
3. Select **Regenerate**.
46+
4. Confirm the action in the modal window.
47+
48+
**Warning:** Regenerating a key invalidates the old key string immediately. You must update any applications or scripts using the old key with the new value to restore connectivity.
49+
50+
[VIDEO: regenerate_apikey.mp4]
51+
{/* <!-- Video showing the regenerate flow and the confirmation modal --> */}
52+
53+
### Editing and Deleting
54+
* **Edit:** Allows you to rename the key or change its expiration settings without changing the key string itself.
55+
* **Delete:** Permanently revokes the key. Applications using this key will no longer be able to connect.
56+
57+
[VIDEO: delete_apikey.mp4]
58+
{/* <!-- Video showing the delete action --> */}
59+
60+
---
61+
62+
## Using API Keys
63+
64+
Once generated, the API Key is typically used in the connection string of your SQLite Cloud client or SDK.
65+
66+
The standard format for a connection string using an API Key is:
67+
```
68+
sqlitecloud://<host>:<port>?apikey=<your-api-key>
69+
```
70+
71+
When using the REST API directly, the key should be passed in the Authorization header:
1872

19-
The resulting table will display all the API keys associated with each user, along with their name.
20-
![Dashboard List APIKEY](@docs-website-assets/introduction/dashboard_list_apikey.png)
73+
```http
74+
Authorization: Bearer <your-api-key>
75+
```

‎sqlite-cloud/platform/pub-sub.mdx‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@ status: publish
66
slug: pub-sub
77
---
88

9-
# SQLiteCloud Pub/Sub System
109

1110
**Publish/Subscribe (Pub/Sub)** is a messaging pattern that enables asynchronous communication between multiple applications. In the context of **SQLiteCloud**, Pub/Sub provides a robust way to deliver real-time updates or custom messages to subscribed clients when data changes or explicit notifications are issued.
1211

‎sqlite-cloud/platform/roles.mdx‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
title: Roles & Privileges
3+
description: Understand the role-based access control system, built-in roles, and how to define custom access policies.
4+
category: platform
5+
status: publish
6+
slug: roles
7+
---
8+
import VideoPlayer from '@commons-components/Video/VideoPlayer.astro';
9+
import createRole from '@docs-website-assets/introduction/video/roles-privileges/roles_create_custom_role.mp4';
10+
import manageRole from '@docs-website-assets/introduction/video/roles-privileges/roles_manage_roles.mp4';
11+
12+
import Callout from "@commons-components/Information/Callout.astro";
13+
14+
15+
16+
In SQLite Cloud, a **Role** is a named collection of permissions (privileges) that allows specific actions on resources like databases, tables. Users can have multiple roles, which determine their access to the system.
17+
18+
Roles are the bridge between Users and Resources:
19+
* **Users** authenticate into the system.
20+
* **Roles** define what those users are allowed to do.
21+
* **Resources** (Databases, Tables) are the objects being accessed.
22+
23+
You can manage role definitions via the SQLite Cloud Dashboard under the **Roles** section.
24+
25+
---
26+
27+
## Built-in Roles
28+
29+
SQLite Cloud comes with a set of pre-defined roles designed to cover the most common use cases. These roles are available immediately and cannot be modified, but they can be scoped to specific databases or tables when assigned to a user.
30+
31+
### General Access Roles
32+
* **ADMIN:** This role possesses the highest level of privileges, with unrestricted access to all assigned permissions.
33+
* **READ:** Grants read-only access to a specified database or table.
34+
* **READWRITE:** Offers both read and write functionality for a specified database or table.
35+
* **DBADMIN:** Allows for administrative tasks like indexing and statistics gathering but doesn't manage users or roles.
36+
37+
### Any Database Roles
38+
These roles implicitly apply to the entire cluster (`*`) and do not require specific scoping during assignment.
39+
* **READANYDATABASE:** Provides read-only access to any database and table.
40+
* **READWRITEANYDATABASE:** Grants read and write capabilities across any database and table.
41+
* **DBADMINANYDATABASE:** Provides administrative functions for any database.
42+
43+
### Pub/Sub Roles
44+
* **SUB:** Grants the subscribe privilege to a specified database, table, or channel.
45+
* **PUB:** Offers the publish privilege to a specified database, table, or channel.
46+
* **PUBSUB:** Combines subscribe and publish privileges for a specified database, table, or channel.
47+
* **PUBSUBADMIN:** Allows the creation and removal of channel privileges for a specified database or channel.
48+
* **SUBANYCHANNEL**: Provides the subscribe privilege for any channel or table.
49+
* **PUBANYCHANNEL**: Grants the publish privilege for any channel or table.
50+
* **PUBSUBANYCHANNEL**: Combines subscribe and publish privileges for any channel or table.
51+
* **PUBSUBADMINANYCHANNEL**: Permits the creation and removal of channel privileges for any channel.
52+
53+
### Cluster Management Roles
54+
* **USERADMIN:** Enables the creation and modification of roles and users.
55+
* **CLUSTERADMIN:** Empowers users to manage and monitor the cluster.
56+
* **CLUSTERMONITOR:** Offers read-only access to cluster monitoring commands.
57+
* **HOSTADMIN:** Allows monitoring and management of individual nodes.
58+
59+
<Callout type="note" title="Restrictions">
60+
To further refine the scope of a role or privilege, you can specify a database and table name during the [CREATE ROLE](/docs/role-commands), [GRANT ROLE](/docs/role-commands), <a href="https://docs.sqlitecloud.io/docs/privilege-commands" target="_blank">GRANT PRIVILEGE</a> and <a href="https://docs.sqlitecloud.io/docs/privilege-commands" target="_blank">SET PRIVILEGE</a> commands, as well as during the <a href="https://docs.sqlitecloud.io/docs/user-commands" target="_blank">CREATE USER</a> command. If `NULL` is used, it means that the role or privilege is not assigned and cannot function without specifying a database and table name combination. To extend the validity to any database and table, you can utilize the special `*` character.
61+
</Callout>
62+
63+
Below is the technical definition of all built-in roles and their mapped privileges:
64+
65+
```bash
66+
>> LIST ROLES
67+
-----------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------|--------------|-----------|
68+
rolename | builtin | privileges | databasename | tablename |
69+
-----------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------|--------------|-----------|
70+
ADMIN | 1 | READ,INSERT,UPDATE,DELETE,READWRITE,PRAGMA,CREATE_TABLE,CREATE_INDEX,CREATE_VIEW, | | |
71+
| | CREATE_TRIGGER,DROP_TABLE,DROP_INDEX,DROP_VIEW,DROP_TRIGGER,ALTER_TABLE,ANALYZE, | | |
72+
| | ATTACH,DETACH,DBADMIN,SUB,PUB,PUBSUB,BACKUP,RESTORE,DOWNLOAD,PLUGIN,SETTINGS,USERADMIN, | | |
73+
| | CLUSTERADMIN,CLUSTERMONITOR,CREATE_DATABASE,DROP_DATABASE,HOSTADMIN,SWITCH_USER,PUBSUBCREATE,PUBSUBADMIN,WEBLITE,ADMIN | NULL | NULL |
74+
READ | 1 | READ | NULL | NULL |
75+
READANYDATABASE | 1 | READ | * | * |
76+
READWRITE | 1 | READ,INSERT,UPDATE,DELETE,READWRITE | NULL | NULL |
77+
READWRITEANYDATABASE | 1 | READ,INSERT,UPDATE,DELETE,READWRITE | * | * |
78+
DBADMIN | 1 | READ,INSERT,UPDATE,DELETE,READWRITE,PRAGMA,CREATE_TABLE,CREATE_INDEX,CREATE_VIEW, | | |
79+
| | CREATE_TRIGGER,DROP_TABLE,DROP_INDEX,DROP_VIEW,DROP_TRIGGER,ALTER_TABLE,ANALYZE,ATTACH,DETACH,DBADMIN | NULL | NULL |
80+
DBADMINANYDATABASE | 1 | READ,INSERT,UPDATE,DELETE,READWRITE,PRAGMA,CREATE_TABLE,CREATE_INDEX,CREATE_VIEW, | | |
81+
| | CREATE_TRIGGER,DROP_TABLE,DROP_INDEX,DROP_VIEW,DROP_TRIGGER,ALTER_TABLE,ANALYZE,ATTACH,DETACH,DBADMIN | * | * |
82+
USERADMIN | 1 | USERADMIN | * | * |
83+
CLUSTERADMIN | 1 | CLUSTERADMIN | * | * |
84+
CLUSTERMONITOR | 1 | CLUSTERMONITOR | * | * |
85+
HOSTADMIN | 1 | BACKUP,RESTORE,DOWNLOAD,CREATE_DATABASE,DROP_DATABASE,HOSTADMIN | * | * |
86+
SUB | 1 | SUB | NULL | NULL |
87+
SUBANYCHANNEL | 1 | SUB | * | * |
88+
PUB | 1 | PUB | NULL | NULL |
89+
PUBANYCHANNEL | 1 | PUB | * | * |
90+
PUBSUB | 1 | SUB,PUB,PUBSUB | NULL | NULL |
91+
PUBSUBANYCHANNEL | 1 | SUB,PUB,PUBSUB | * | * |
92+
PUBSUBADMIN | 1 | SUB,PUB,PUBSUB,PUBSUBCREATE,PUBSUBADMIN | NULL | NULL |
93+
PUBSUBADMINANYCHANNEL | 1 | SUB,PUB,PUBSUB,PUBSUBCREATE,PUBSUBADMIN | * | * |
94+
-----------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------|--------------|-----------|
95+
```
96+
97+
---
98+
99+
## Custom Roles
100+
101+
If the built-in roles do not fit your specific security model, you can create **User-Defined Roles**. This allows you to mix and match specific privileges.
102+
103+
### Creating a Custom Role
104+
105+
1. Navigate to the **Roles** section in the left sidebar.
106+
2. Click the **Create Role** button.
107+
3. **Name:** Enter a unique name for the role (e.g., `AuditLogger`, `HRManager`).
108+
4. **Privileges:** Select the specific atomic privileges this role should possess (see list below).
109+
5. Click **Create**.
110+
111+
<VideoPlayer src={createRole} />
112+
113+
### Managing Roles
114+
115+
From the Roles list, you can:
116+
* **Inspect:** Click on a role to see exactly which privileges it contains.
117+
* **Edit:** Add or remove privileges from a custom role (Built-in roles cannot be edited).
118+
* **Delete:** Remove a custom role.
119+
120+
<VideoPlayer src={manageRole} />
121+
122+
---
123+
124+
## Privileges Reference
125+
126+
In a role-based access control system, a **Privilege** represents a specific action or permission that a user or role is allowed to perform within the system.
127+
It defines what a user can or cannot do, such as reading, writing, or managing certain resources like tables, databases, or settings.
128+
Essentially, a privilege is a **right** or **ability** granted to a user or role, specifying their level of access and control over the system's resources.
129+
130+
A privilege can be <a href="https://docs.sqlitecloud.io/docs/privilege-commands" target="_blank">granted</a>, <a href="https://docs.sqlitecloud.io/docs/privilege-commands" target="_blank">revoked</a> and <a href="https://docs.sqlitecloud.io/docs/privilege-commands" target="_blank">assigned</a> to a given role.
131+
A role can contains any combination of privileges.
132+
133+
Below is the complete list of available privileges:
134+
135+
| | | |
136+
| :--- | :--- | :--- |
137+
| NONE | READ | INSERT |
138+
| UPDATE | DELETE | READWRITE |
139+
| PRAGMA | CREATE_TABLE | CREATE_INDEX |
140+
| CREATE_VIEW | CREATE_TRIGGER | DROP_TABLE |
141+
| DROP_INDEX | DROP_VIEW | DROP_TRIGGER |
142+
| ALTER_TABLE | ANALYZE | ATTACH |
143+
| DETACH | DBADMIN | SUB |
144+
| PUB | PUBSUB | BACKUP |
145+
| RESTORE | DOWNLOAD | PLUGIN |
146+
| SETTINGS | USERADMIN | CLUSTERADMIN |
147+
| CLUSTERMONITOR | CREATE_DATABASE | DROP_DATABASE |
148+
| HOSTADMIN | SWITCH_USER | PUBSUBCREATE |
149+
| PUBSUBADMIN | WEBLITE | ADMIN |

‎sqlite-cloud/platform/security.mdx‎

Lines changed: 0 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -38,24 +38,9 @@ SQLite Cloud offers a comprehensive system of built-in roles designed to provide
3838

3939
Here is an overview of the built-in roles:
4040

41-
- **ADMIN**: This role possesses the highest level of privileges, with unrestricted access to all assigned permissions.
42-
- **READ**: Grants read-only access to a specified database or table.
43-
- **READANYDATABASE**: Provides read-only access to any database and table.
44-
- **READWRITE**: Offers both read and write functionality for a specified database or table.
45-
- **READWRITEANYDATABASE**: Grants read and write capabilities across any database and table.
46-
- **DBADMIN**: Allows for administrative tasks like indexing and statistics gathering but doesn't manage users or roles.
47-
- **DBADMINANYDATABASE**: Provides administrative functions for any database.
48-
- **USERADMIN**: Enables the creation and modification of roles and users.
49-
- **CLUSTERADMIN**: Empowers users to manage and monitor the cluster.
50-
- **CLUSTERMONITOR**: Offers read-only access to cluster monitoring commands.
51-
- **HOSTADMIN**: Allows monitoring and management of individual nodes.
52-
- **SUB**: Grants the subscribe privilege to a specified database, table, or channel.
5341
- **SUBANYCHANNEL**: Provides the subscribe privilege for any channel or table.
54-
- **PUB**: Offers the publish privilege to a specified database, table, or channel.
5542
- **PUBANYCHANNEL**: Grants the publish privilege for any channel or table.
56-
- **PUBSUB**: Combines subscribe and publish privileges for a specified database, table, or channel.
5743
- **PUBSUBANYCHANNEL**: Combines subscribe and publish privileges for any channel or table.
58-
- **PUBSUBADMIN**: Allows the creation and removal of channel privileges for a specified database or channel.
5944
- **PUBSUBADMINANYCHANNEL**: Permits the creation and removal of channel privileges for any channel.
6045

6146

0 commit comments

Comments
 (0)