Skip to content

Commit 090b4da

Browse files
skeptrunedevskeptrunedev
committed
feature: docs for using exposed API keys
1 parent a365dec commit 090b4da

File tree

2 files changed

+145
-0
lines changed

2 files changed

+145
-0
lines changed

‎guides/using-exposed-api-keys.mdx

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
title: "Using Exposed API keys with Trieve"
3+
description: "Learn how to create and use safe, access controlled api keys with Trieve"
4+
icon: 'key'
5+
---
6+
7+
## Overview
8+
9+
Proxying search and recommendations through your server is usually a bad idea. It adds latency, complexity, and can be a security risk. Instead, Trieve allows you to create and manage API keys that can be used directly in the client.
10+
11+
To create an API key, use the [create API key](/api-reference/api-key/create-api-key) route.
12+
13+
- TS-SDK method: [createApiKey](https://ts-sdk.trieve.ai/functions/User_Methods.createUserApiKey.html)
14+
- Python SDK method: [create_api_key](https://github.com/devflowinc/trieve/blob/main/clients/python-sdk/trieve_py_client/api/user_api.py#L45)
15+
16+
Roughly, you can visualize the flow we are encouraging with the following diagram. Information on how to scope down the access a given API key has is provided are in the next several sections.
17+
18+
![scoped api key pattern diagram](https://trieve.b-cdn.net/docs/client-api-key-req-pattern.png)
19+
20+
All of the below examples can be used in combination with each other. For example, you can create an API key that can only access specific organizations, datasets, and tags within those datasets.
21+
22+
## Limit to read-only access
23+
24+
Specify the `role` field with the value `0` in your request.
25+
26+
```json curl {7}
27+
curl --request POST \
28+
--url https://api.trieve.ai/api/user/api_key \
29+
--header 'Authorization
30+
--header 'Content-Type: application/json' \
31+
--data '{
32+
"name": "Read only API key",
33+
"role": 0
34+
}'
35+
```
36+
37+
## Set a time expiry
38+
39+
Specify the `expires_at` field with the time in the future that the API key should expire in your request. This field accepts only ISO 8601 formatted dates.
40+
41+
```json curl {6}
42+
curl --request POST \
43+
--url https://api.trieve.ai/api/user/api_key \
44+
--header 'Authorization: <api-key>' \
45+
--header 'Content-Type: application/json' \
46+
--data '{
47+
"name": "expires at '2024-11-14 00:00:00' UTC",
48+
"expires_at": "2024-11-14 00:00:00",
49+
"role": 0,
50+
}'
51+
```
52+
53+
## Scope access to specific organizations
54+
55+
Specify the `organization_ids` field with the organization IDs that the API key should have access to in your request.
56+
57+
```json curl {7-9}
58+
curl --request POST \
59+
--url https://api.trieve.ai/api/user/api_key \
60+
--header 'Authorization: <api-key>' \
61+
--header 'Content-Type: application/json' \
62+
--data '{
63+
"name": "Can only make requests to the 3c90c3cc... organization",
64+
"organization_ids": [
65+
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
66+
],
67+
"role": 1,
68+
}'
69+
```
70+
71+
## Scope access to specific datasets
72+
73+
Specify the `dataset_ids` field with the dataset IDs that the API key should have access to in your request.
74+
75+
```json curl {7-9}
76+
curl --request POST \
77+
--url https://api.trieve.ai/api/user/api_key \
78+
--header 'Authorization: <api-key>' \
79+
--header 'Content-Type: application/json' \
80+
--data '{
81+
"name": "Can only make requests to the 9u90c3cc... dataset",
82+
"dataset_ids": [
83+
"9u90c3cc-0d44-4b50-8888-8dd25736052a"
84+
],
85+
"role": 1,
86+
}'
87+
```
88+
89+
## Scope access to specific routes
90+
91+
```json curl {7-21}
92+
curl --request POST \
93+
--url https://api.trieve.ai/api/user/api_key \
94+
--header 'Authorization: <api-key>' \
95+
--header 'Content-Type: application/json' \
96+
--data '{
97+
"name": "Can only make requests to the 9u90c3cc... dataset",
98+
"scopes": [
99+
"POST /api/chunk/search",
100+
"POST /api/chunk_group/search",
101+
"POST /api/chunk/autocomplete",
102+
"POST /api/chunk_group/group_oriented_search",
103+
"POST /api/chunk/suggestions",
104+
"POST /api/chunk/count",
105+
"PUT /api/analytics/ctr",
106+
"PUT /api/analytics/search",
107+
"PUT /api/analytics/events",
108+
"PUT /api/analytics/rag",
109+
"POST /api/topic",
110+
"POST /api/message",
111+
"PUT /api/message"
112+
],
113+
"role": 1,
114+
}'
115+
```
116+
117+
## Scope access to chunks matching a filter or other search request payload fields
118+
119+
Specify a filter in the `default_params` field in your request. This filter will be applied to all requests made with this API key.
120+
121+
You can use this to restrict access to data with more granularity than just dataset or organization.
122+
123+
```json curl {7-18}
124+
curl --request POST \
125+
--url https://api.trieve.ai/api/user/api_key \
126+
--header 'Authorization: <api-key>' \
127+
--header 'Content-Type: application/json' \
128+
--data '{
129+
"name": "Can only access chunks with the tag bucket-id-with-protected-access",
130+
"default_params": {
131+
"filters": {
132+
"must": [
133+
{
134+
"field": "tag_set",
135+
"match_all": [
136+
"bucket-id-with-protected-access",
137+
]
138+
},
139+
]
140+
},
141+
},
142+
"role": 0,
143+
}'
144+
```

‎mint.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,7 @@
116116
"guides/analytics-quickstart",
117117
"guides/create-organizations-and-dataset",
118118
"guides/group-with-trieve",
119+
"guides/using-exposed-api-keys",
119120
"vector-inference/rerank",
120121
"vector-inference/splade",
121122
"vector-inference/dense",

0 commit comments

Comments
 (0)