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