78 lines
1.9 KiB
Markdown
78 lines
1.9 KiB
Markdown
|
# SDK Generation
|
||
|
|
|
||
|
|
> **Disclaimer:** The Hemmelig API is subject to change without notice. Generated SDKs may break with future updates. Use at your own risk.
|
||
|
|
|
||
|
|
Hemmelig exposes an OpenAPI 3.0 specification that can be used to generate client SDKs in various programming languages.
|
||
|
|
|
||
|
|
## OpenAPI Specification
|
||
|
|
|
||
|
|
The OpenAPI spec is available at:
|
||
|
|
|
||
|
|
- **Swagger UI:** `/api/docs` - Interactive API explorer
|
||
|
|
- **OpenAPI JSON:** `/api/openapi.json` - Raw specification
|
||
|
|
|
||
|
|
## Generating an SDK
|
||
|
|
|
||
|
|
We recommend using [OpenAPI Generator](https://openapi-generator.tech/) which supports 50+ languages.
|
||
|
|
|
||
|
|
### Installation
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm install -g @openapitools/openapi-generator-cli
|
||
|
|
```
|
||
|
|
|
||
|
|
### Generate SDK
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# TypeScript
|
||
|
|
openapi-generator-cli generate \
|
||
|
|
-i https://your-instance.com/api/openapi.json \
|
||
|
|
-g typescript-axios \
|
||
|
|
-o ./hemmelig-sdk
|
||
|
|
|
||
|
|
# Python
|
||
|
|
openapi-generator-cli generate \
|
||
|
|
-i https://your-instance.com/api/openapi.json \
|
||
|
|
-g python \
|
||
|
|
-o ./hemmelig-sdk
|
||
|
|
|
||
|
|
# Go
|
||
|
|
openapi-generator-cli generate \
|
||
|
|
-i https://your-instance.com/api/openapi.json \
|
||
|
|
-g go \
|
||
|
|
-o ./hemmelig-sdk
|
||
|
|
```
|
||
|
|
|
||
|
|
View all available generators:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
openapi-generator-cli list
|
||
|
|
```
|
||
|
|
|
||
|
|
## Authentication
|
||
|
|
|
||
|
|
The API supports two authentication methods:
|
||
|
|
|
||
|
|
### Bearer Token (API Key)
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
const client = new HemmeligApi({
|
||
|
|
baseURL: 'https://your-instance.com/api',
|
||
|
|
headers: {
|
||
|
|
Authorization: 'Bearer hemmelig_your_api_key_here',
|
||
|
|
},
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
### Session Cookie
|
||
|
|
|
||
|
|
For browser-based applications, session cookies are automatically handled after authentication via `/auth` endpoints.
|
||
|
|
|
||
|
|
## Important: Client-Side Encryption
|
||
|
|
|
||
|
|
Generated SDKs handle API communication only. **You must implement client-side encryption** before sending secrets to the API.
|
||
|
|
|
||
|
|
Hemmelig uses AES-256-GCM encryption. See the [encryption documentation](./encryption.md) for implementation details.
|
||
|
|
|
||
|
|
The decryption key should be passed via URL fragments (`#decryptionKey=...`) which are never sent to the server.
|