Create Custom API Keys
Create and manage API keys with specific permissions and expiration dates. You need an admin API key with root path access to create new keys.
POST
/api-key
Create a new API key with custom permissions
Important Notes
- • You need a root / admin API key (an API key with read + write access to "/" plus no expiration date)
Headers
| Header | Type | Required | Description |
|---|---|---|---|
| x-user-api-key | string | Yes | Your admin API key with root path access |
| Content-Type | application/json | Yes | Request body must be JSON |
Request Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| permissions | number | Yes | 1 (read), 2 (write), or 3 (read+write) |
| path | string | Yes | Absolute path the key can access (includes nested paths) |
| expiration_date | string (RFC3339) | Yes | Expiration date/time (use "0001-01-01T00:00:00Z" for no expiration) |
Example Request
type ApiKeyPermission uint64
const (
PermissionRead ApiKeyPermission = 1 << 0
PermissionWrite ApiKeyPermission = 1 << 1
)
func CreateApiKey(permissions ApiKeyPermission, path string, expirationDate time.Time) (key string) {
type CreateApiKeyReqBody struct {
Permissions ApiKeyPermission `json:"permissions"`
Path string `json:"path"`
ExpirationDate time.Time `json:"expiration_date"`
}
requestBody := CreateApiKeyReqBody{
Permissions: permissions,
Path: path,
ExpirationDate: expirationDate,
}
jsonBody, err := json.Marshal(requestBody)
if err != nil {
panic(fmt.Errorf("could not marshal CreateApiKey request body: %w", err))
}
url := fmt.Sprintf("%s/api-key", SHARD_NODE_URL)
req, err := http.NewRequest(http.MethodPost, url, strings.NewReader(string(jsonBody)))
if err != nil {
panic(fmt.Errorf("could not create POST request to /api-key: %w", err))
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("x-user-api-key", API_KEY)
client := http.DefaultClient
resp, err := client.Do(req)
if err != nil {
panic(fmt.Errorf("Response error from shard: %w", err))
}
if resp.StatusCode != http.StatusCreated {
body, _ := io.ReadAll(resp.Body)
panic(fmt.Sprintf("Create API key failed with status %d: %s", resp.StatusCode, string(body)))
}
body, err := io.ReadAll(resp.Body)
if err != nil {
panic(fmt.Errorf("Could not read api key value from successful api key creation: %w", err))
}
return string(body)
}
enum ApiKeyPermission {
Read = 1 << 0,
Write = 1 << 1,
ReadWrite = Read | Write
}
interface CreateApiKeyRequestBody {
permissions: number;
path: string;
expiration_date: string;
}
interface DeleteApiKeyRequestBody {
value: string;
}
async function createApiKey(
permissions: ApiKeyPermission,
path: string,
expirationDate: Date
): Promise<string> {
const requestBody: CreateApiKeyRequestBody = {
permissions: permissions,
path: path,
expiration_date: expirationDate.toISOString()
};
const url = `${SHARD_NODE_URL}/api-key`;
const res = await fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-user-api-key': API_KEY
},
body: JSON.stringify(requestBody)
});
if (res.status !== 201) {
const body = await res.text();
throw new Error(`Create API key failed with status ${res.status}: ${body}`);
}
const apiKey = await res.text();
return apiKey;
}
Response Status Codes
| Code | Status | Description |
|---|---|---|
| 201 | Created | API key created successfully (returns key in response body) |
| 400 | Bad Request | Invalid request parameters |
| 401 | Unauthorized | Invalid or missing API key |
| 5xx | Server Error | Internal server error - check response body for details |