Skip to content

Commit 86aa54c

Browse files
marythoughtclaude
marythought
and
claude
committed
docs(sdk): add KAS Registry page with full API coverage
Adds a new standalone SDK docs page covering all KeyAccessServerRegistry service methods across Go, Java, and JavaScript SDKs. Includes Setup section, KAS server CRUD, and key management operations. Each method follows the Signature/Parameters/Example/Returns/Errors pattern. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 2fd6c69 commit 86aa54c

3 files changed

Lines changed: 1481 additions & 0 deletions

File tree

‎code_samples/policy_code/create_kas.mdx‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
import Tabs from '@theme/Tabs';
2+
import TabItem from '@theme/TabItem';
3+
4+
<details id="create-kas-server">
5+
<summary>CreateKeyAccessServer</summary>
6+
7+
Registers a new Key Access Server (KAS) with the platform.
8+
9+
**Signature**
10+
11+
<Tabs>
12+
<TabItem value="go" label="Go">
13+
14+
```go
15+
func (c KeyAccessServerRegistryServiceClient) CreateKeyAccessServer(
16+
ctx context.Context,
17+
req *kasregistry.CreateKeyAccessServerRequest,
18+
) (*kasregistry.CreateKeyAccessServerResponse, error)
19+
```
20+
21+
</TabItem>
22+
<TabItem value="java" label="Java">
23+
24+
```java
25+
CreateKeyAccessServerResponse createKeyAccessServerBlocking(
26+
CreateKeyAccessServerRequest request, Map<String, String> metadata
27+
)
28+
```
29+
30+
</TabItem>
31+
<TabItem value="js" label="JavaScript">
32+
33+
```typescript
34+
keyAccessServerRegistry.createKeyAccessServer(
35+
request: CreateKeyAccessServerRequest
36+
): Promise<CreateKeyAccessServerResponse>
37+
```
38+
39+
</TabItem>
40+
</Tabs>
41+
42+
**Parameters**
43+
44+
| Parameter | Type | Required | Description |
45+
|-----------|------|----------|-------------|
46+
| `uri` | `string` | Yes | URL of the KAS instance (e.g., `https://kas.example.com`). |
47+
| `name` | `string` | No | Unique name for the KAS (alphanumeric, hyphens, underscores; max 253 chars; normalized to lowercase). |
48+
| `source_type` | `SourceType` | No | `INTERNAL` (managed by your org) or `EXTERNAL` (managed by an external party). |
49+
| `metadata` | `MetadataMutable` | No | Labels to attach (key-value string pairs). |
50+
51+
**Example**
52+
53+
<Tabs>
54+
<TabItem value="go" label="Go">
55+
56+
```go
57+
import (
58+
"github.com/opentdf/platform/protocol/go/policy"
59+
"github.com/opentdf/platform/protocol/go/policy/kasregistry"
60+
)
61+
62+
resp, err := client.KeyAccessServerRegistry.CreateKeyAccessServer(context.Background(),
63+
&kasregistry.CreateKeyAccessServerRequest{
64+
Uri: "https://kas.example.com",
65+
Name: "my-kas",
66+
SourceType: policy.SourceType_SOURCE_TYPE_INTERNAL,
67+
},
68+
)
69+
if err != nil {
70+
log.Fatal(err)
71+
}
72+
log.Printf("Created KAS: %s (ID: %s)\n", resp.GetKeyAccessServer().GetName(), resp.GetKeyAccessServer().GetId())
73+
```
74+
75+
</TabItem>
76+
<TabItem value="java" label="Java">
77+
78+
```java
79+
import io.opentdf.platform.policy.SourceType;
80+
import io.opentdf.platform.policy.kasregistry.CreateKeyAccessServerRequest;
81+
82+
var req = CreateKeyAccessServerRequest.newBuilder()
83+
.setUri("https://kas.example.com")
84+
.setName("my-kas")
85+
.setSourceType(SourceType.SOURCE_TYPE_INTERNAL)
86+
.build();
87+
var resp = sdk.getServices().kasRegistry()
88+
.createKeyAccessServerBlocking(req, Collections.emptyMap()).execute();
89+
System.out.println("Created KAS: " + resp.getKeyAccessServer().getName()
90+
+ " (ID: " + resp.getKeyAccessServer().getId() + ")");
91+
```
92+
93+
</TabItem>
94+
<TabItem value="js" label="JavaScript">
95+
96+
```typescript
97+
import { SourceType } from '@opentdf/sdk/platform/policy/objects_pb.js';
98+
99+
const resp = await platform.v1.keyAccessServerRegistry.createKeyAccessServer({
100+
uri: 'https://kas.example.com',
101+
name: 'my-kas',
102+
sourceType: SourceType.INTERNAL,
103+
});
104+
console.log(`Created KAS: ${resp.keyAccessServer?.name} (ID: ${resp.keyAccessServer?.id})`);
105+
```
106+
107+
</TabItem>
108+
</Tabs>
109+
110+
**Returns**
111+
112+
The created `KeyAccessServer` object, including its generated `id`, `uri`, `name`, `source_type`, and `metadata` with server-set timestamps.
113+
114+
**Errors**
115+
116+
| Error | Cause |
117+
|-------|-------|
118+
| Already exists | A KAS with the same `uri` or `name` is already registered. |
119+
| Invalid argument | The `uri` is not a valid URL, or the `name` violates naming constraints. |
120+
| Permission denied | The caller lacks permission to create KAS entries. |
121+
122+
</details>

‎code_samples/policy_code/list_kas.mdx‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
import Tabs from '@theme/Tabs';
2+
import TabItem from '@theme/TabItem';
3+
4+
<details id="list-kas-servers">
5+
<summary>ListKeyAccessServers</summary>
6+
7+
Returns all registered Key Access Servers, with optional pagination.
8+
9+
**Signature**
10+
11+
<Tabs>
12+
<TabItem value="go" label="Go">
13+
14+
```go
15+
func (c KeyAccessServerRegistryServiceClient) ListKeyAccessServers(
16+
ctx context.Context,
17+
req *kasregistry.ListKeyAccessServersRequest,
18+
) (*kasregistry.ListKeyAccessServersResponse, error)
19+
```
20+
21+
</TabItem>
22+
<TabItem value="java" label="Java">
23+
24+
```java
25+
ListKeyAccessServersResponse listKeyAccessServersBlocking(
26+
ListKeyAccessServersRequest request, Map<String, String> metadata
27+
)
28+
```
29+
30+
</TabItem>
31+
<TabItem value="js" label="JavaScript">
32+
33+
```typescript
34+
keyAccessServerRegistry.listKeyAccessServers(
35+
request: ListKeyAccessServersRequest
36+
): Promise<ListKeyAccessServersResponse>
37+
```
38+
39+
</TabItem>
40+
</Tabs>
41+
42+
**Parameters**
43+
44+
| Parameter | Type | Required | Description |
45+
|-----------|------|----------|-------------|
46+
| `pagination.limit` | `int32` | No | Maximum number of results to return. |
47+
| `pagination.offset` | `int32` | No | Number of results to skip. |
48+
49+
**Example**
50+
51+
<Tabs>
52+
<TabItem value="go" label="Go">
53+
54+
```go
55+
import "github.com/opentdf/platform/protocol/go/policy/kasregistry"
56+
57+
resp, err := client.KeyAccessServerRegistry.ListKeyAccessServers(context.Background(),
58+
&kasregistry.ListKeyAccessServersRequest{},
59+
)
60+
if err != nil {
61+
log.Fatal(err)
62+
}
63+
for _, kas := range resp.GetKeyAccessServers() {
64+
log.Printf("KAS: %s — %s (source: %s)\n", kas.GetName(), kas.GetUri(), kas.GetSourceType())
65+
}
66+
```
67+
68+
</TabItem>
69+
<TabItem value="java" label="Java">
70+
71+
```java
72+
import io.opentdf.platform.policy.kasregistry.ListKeyAccessServersRequest;
73+
74+
var req = ListKeyAccessServersRequest.newBuilder().build();
75+
var resp = sdk.getServices().kasRegistry()
76+
.listKeyAccessServersBlocking(req, Collections.emptyMap()).execute();
77+
for (var kas : resp.getKeyAccessServersList()) {
78+
System.out.println("KAS: " + kas.getName() + " — " + kas.getUri()
79+
+ " (source: " + kas.getSourceType() + ")");
80+
}
81+
```
82+
83+
</TabItem>
84+
<TabItem value="js" label="JavaScript">
85+
86+
```typescript
87+
const resp = await platform.v1.keyAccessServerRegistry.listKeyAccessServers({});
88+
for (const kas of resp.keyAccessServers) {
89+
console.log(`KAS: ${kas.name} — ${kas.uri} (source: ${kas.sourceType})`);
90+
}
91+
```
92+
93+
</TabItem>
94+
</Tabs>
95+
96+
**Returns**
97+
98+
A list of `KeyAccessServer` objects and a `pagination` response containing `current_offset`, `next_offset`, and `total` count.
99+
100+
**Errors**
101+
102+
| Error | Cause |
103+
|-------|-------|
104+
| Permission denied | The caller lacks permission to list KAS entries. |
105+
106+
</details>

0 commit comments

Comments
 (0)