Skip to content

Commit 4c64125

Browse files
danielebriggidanielebriggi
committed
feat(accessTokens): explain the access tokens example
1 parent e566c16 commit 4c64125

File tree

1 file changed

+55
-218
lines changed

1 file changed

+55
-218
lines changed

‎sqlite-cloud/platform/access-tokens.mdx‎

Lines changed: 55 additions & 218 deletions
Original file line numberDiff line numberDiff line change
@@ -8,239 +8,76 @@ slug: access-tokens
88

99
# Access Token API
1010

11-
Access Tokens let backend systems securely grant users, devices, tenants, etc. access to SQLite Cloud database and services (SQLite Sync, Weblite, etc.). These endpoints enable full token lifecycle management: creation, inspection, validation, update, and revocation.
12-
All endpoints require authentication. Use an **API Key** or an **Access Token** via the `Authorization` header.
11+
Access Tokens let backend systems securely grant users, devices, tenants, etc. access to SQLite Cloud database and services (SQLite Sync, Weblite, etc.). These endpoints enable full token lifecycle management: creation, inspection, validation, update, and revocation. All endpoints require authentication. Use an **API Key** or an **Access Token** via the `Authorization` header.
1312

14-
---
15-
16-
## Create a New Access Token
17-
18-
### `POST /v2/tokens`
19-
20-
Creates a new Access Token for a specific user.
21-
The `userId` refers to your user's id or any kind of resource you want to associate the Access Token to. It must be a unique ID in your system.
22-
The `expiresAt` is a date time value to set expiration, or `null` if it doesn't expire.
23-
24-
>[!note] Store the Access Token securely. It will not be shown again.
25-
26-
- **Authentication**: API Key
27-
28-
#### Example
29-
30-
```bash
31-
curl -X 'POST' \
32-
'https://<your-project-domain>.sqlite.cloud/v2/tokens' \
33-
-H 'Content-Type: application/json' \
34-
-H 'Authorization: Bearer <your-api-key>' \
35-
-d '{
36-
"userId": "0195fc5b-96a6-7000-8b17-fd2420499c2c",
37-
"name": "user-token",
38-
"attributes": "{\"role\":\"myrole\"}",
39-
"expiresAt": "2023-10-01 10:11:12"
40-
}'
41-
```
42-
43-
#### Example Response
44-
45-
```json
46-
{
47-
"data": {
48-
"token": "134|sqla_abcdeabcdeabcdeabcdeabcdeabcde",
49-
"access_token_id": 134,
50-
"userId": "0195fc5b-96a6-7000-8b17-fd2420499c2c",
51-
"name": "user-token",
52-
"attributes": "{\"role\":\"myrole\"}",
53-
"expiresAt": "2023-10-01 10:11:12",
54-
"createdAt": "2023-09-01 10:11:12"
55-
}
56-
}
57-
```
13+
API Documentation can be found in the **Weblite** section in the [Dashboard](https://dashboard.sqlitecloud.io).
5814

5915
---
6016

61-
## Get Current Token Details (Access Token Only)
62-
63-
### `GET /v2/tokens/details`
17+
In the repository on GitHub [sqlitecloud/examples](https://github.com/sqlitecloud/examples), we created a simple app to demonstrate how to generate and use Access Tokens.
6418

65-
Retrieves metadata about the token used to authenticate the request.
19+
We’ll log in with Google, grab a token, and use it to interact with SQLite Cloud Weblite APIs. Here’s how it works.
6620

67-
- **Authentication**: Access Token
21+
## Generate a new Access Token
6822

69-
#### Example
23+
In the snippet below, we handle the Google Login callback when the user has completed the login on Google. Here, you can exchange the `code` with the Google Access Token and then decide what to do with it as needed.
7024

71-
```bash
72-
curl -X 'GET' \
73-
'https://<your-project-domain>.sqlite.cloud/v2/tokens/details' \
74-
-H 'accept: application/json' \
75-
-H 'Authorization: Bearer 134|sqla_abcdeabcdeabcdeabcdeabcdeabcde'
76-
```
77-
78-
#### Example Response
79-
80-
```json
81-
{
82-
"data": {
83-
"access_token_id": 134,
84-
"userId": "0195fc5b-96a6-7000-8b17-fd2420499c2c",
85-
"name": "user-token",
86-
"attributes": null,
87-
"expiresAt": "2023-10-01 10:11:12",
88-
"createdAt": "2023-09-01 10:11:12"
25+
```typescript
26+
if (pathname === "/auth/callback") {
27+
const q = query;
28+
if (q.state !== STATE || !q.code) {
29+
return send(res, 400, "Invalid state or missing code");
8930
}
90-
}
91-
```
9231

93-
---
94-
95-
## Get Token Details (Using API Key)
96-
97-
### `POST /v2/tokens/details`
98-
99-
Lets you inspect an Access Token using your API Key.
100-
101-
- **Authentication**: API Key
102-
103-
#### Example
104-
105-
```bash
106-
curl -X 'POST' \
107-
'https://<your-project-domain>.sqlite.cloud/v2/tokens/details' \
108-
-H 'Content-Type: application/json' \
109-
-H 'Authorization: Bearer <your-api-key>' \
110-
-d '{
111-
"token": "134|sqla_abcdeabcdeabcdeabcdeabcdeabcde"
112-
}'
32+
try {
33+
// Exchange code for tokens
34+
// Store the Google Token in the database
35+
const googleToken = await getGoogleTokens(q.code as string);
36+
...
11337
```
11438
115-
#### Example Response
116-
117-
```json
118-
{
119-
"data": {
120-
"access_token_id": 134,
121-
"userId": "0195fc5b-96a6-7000-8b17-fd2420499c2c",
122-
"name": "user-token",
123-
"attributes": null,
124-
"expiresAt": "2023-10-01 10:11:12",
125-
"createdAt": "2023-09-01 10:11:12"
39+
Now we have authenticated the user, we are ready to request SQLite Cloud to create a new SQLite Cloud Access Token to assign to the this user.
40+
41+
```typescript
42+
async function getSQLiteCloudToken(userId: string) {
43+
const payload = {
44+
name: "test-user-token", // A name for the token, can be anything you want
45+
userId,
46+
expiresAt: new Date(Date.now() + 1000 * 60 * 60 * 24).toISOString(), // expires in 24 hours
47+
};
48+
49+
const res = await fetch(SQLITE_CLOUD_API_TOKENS, {
50+
method: "POST",
51+
headers: {
52+
Authorization: `Bearer ${SQLITE_CLOUD_API_KEY}`,
53+
"Content-Type": "application/json",
54+
},
55+
body: JSON.stringify(payload),
56+
});
57+
if (!res.ok) {
58+
throw new Error(`Failed to create SQLite Cloud token: ${res.statusText}`);
12659
}
127-
}
128-
```
129-
130-
---
131-
132-
## Check Token Validity
133-
134-
### `GET /v2/tokens/authorized`
135-
136-
Checks whether the provided Access Token is valid and not expired.
137-
138-
- **Authentication**: API Key or Access Token
139-
140-
#### Example
14160

142-
```bash
143-
curl -X 'GET' \
144-
'https://<your-project-domain>.sqlite.cloud/v2/tokens/authorized' \
145-
-H 'accept: application/json' \
146-
-H 'Authorization: Bearer 134|sqla_abcdeabcdeabcdeabcdeabcdeabcde'
147-
```
148-
149-
#### Example Response
150-
151-
HTTP Status **204** or **401** if not valid or expired.
152-
153-
---
154-
155-
## Update an Access Token
156-
157-
### `PATCH /v2/tokens`
158-
159-
Updates information of an Access Token.
160-
The `token` field is required, it specifies the Access Token to update.
161-
Fields that can be updated:
162-
- `name`.
163-
- `expiresAt`: date time value or `null` to set no expiration.
164-
165-
- **Authentication**: API Key
166-
167-
#### Example
168-
169-
```bash
170-
curl -X 'PATCH' \
171-
'https://<your-project-domain>.sqlite.cloud/v2/tokens' \
172-
-H 'accept: application/json' \
173-
-H 'Content-Type: application/json' \
174-
-H 'Authorization: Bearer <your-api-key>' \
175-
-d '{
176-
"token": "134|sqla_abcdeabcdeabcdeabcdeabcdeabcde",
177-
"name": "updated-user-token",
178-
"expiresAt": "2024-12-31T23:59:59"
179-
}'
180-
```
181-
182-
---
183-
184-
## Revoke a Token
185-
186-
### `DELETE /v2/tokens`
187-
188-
Revokes the given token, making it immediately unusable.
189-
190-
- **Authentication**: API Key, Access Token
191-
192-
The `token` in the request is optional when the Access Token is used for the authentication.
193-
194-
#### Example
195-
196-
```bash
197-
curl -X 'DELETE' \
198-
'https://<your-project-domain>.sqlite.cloud/v2/tokens' \
199-
-H 'accept: application/json' \
200-
-H 'Content-Type: application/json' \
201-
-H 'Authorization: Bearer <your-api-key>' \
202-
-d '{
203-
"token": "134|sqla_abcdeabcdeabcdeabcdeabcdeabcde"
204-
}'
205-
```
206-
207-
---
208-
209-
## List Tokens by User
210-
211-
### `GET /v2/tokens/users/{userId}`
212-
213-
Returns all non-expired tokens associated with the specified user.
214-
215-
- **Authentication**: API Key
216-
- **Path Parameter**: `userId`
217-
218-
#### Example
219-
220-
```bash
221-
curl -X 'GET' \
222-
'https://<your-project-domain>.sqlite.cloud/v2/tokens/users/0195fc5b-96a6-7000-8b17-fd2420499c2c' \
223-
-H 'accept: application/json' \
224-
-H 'Authorization: Bearer <your-api-key>'
61+
return res.json();
62+
}
22563
```
22664
227-
#### Example Response
228-
229-
```json
230-
{
231-
"data": [
232-
{
233-
"name": "sqlitesync-user",
234-
"expiresAt": "2024-11-01 00:00:00",
235-
"createdAt": "2024-10-01 10:11:12"
236-
},
237-
{
238-
"name": "sqlitesync-user",
239-
"expiresAt": null,
240-
"createdAt": "2024-09-01 10:11:12"
241-
}
242-
]
243-
}
65+
In the response JSON, the `data.token` field contains the Access Token.
66+
67+
Finally, the user is authorized to securely access SQLite Cloud services like the Weblite API to perform a query on the database:
68+
69+
```typescript
70+
const res = await fetch(sqliteCloudApiQuery, {
71+
method: "POST",
72+
headers: {
73+
Authorization: "Bearer " + sqliteCloudToken,
74+
"Content-Type": "application/json",
75+
},
76+
body: JSON.stringify({
77+
sql: "USE DATABASE chinook.sqlite;SELECT * FROM artists LIMIT 10;",
78+
}),
79+
});
80+
...
24481
```
24582
246-
---
83+
The results depend on the [Row Level Security](https://) you enabled for the tables.

0 commit comments

Comments
 (0)