Query API Keys

Query information about your API keys. You can retrieve all keys or query a specific key by its value.

GET /api-key

Query API key information - get all keys or a specific key

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 ADMIN_API_KEY Yes Your admin API key with root path access

Query Parameters (for single key)

Parameter Type Required Description
value string No Specific API key value to query (omit to get all keys)

Response Structure

If you requested information about 1 API key you will get a JSON looking like this:

Field Type Description
permissions number '1' (read), '2' (write), or '3' (read+write)
path string Absolute path the key can access
expiration_date string (RFC3339) Expiration date/time ("0001-01-01T00:00:00Z" means no expiration)

Example


{
  "permissions": 3,
  "path": "/files/",
  "expiration_date": "0001-01-01T00:00:00Z"
}

Else if you requested information about all of your API keys you will get a JSON object where you'll have each key's value alongside its info just like above

so you might get: 

{
  "SOME-API-KEY-VALUE-1": {
    "permissions": 3,
    "path": "/files/",
    "expiration_date": "0001-01-01T00:00:00Z"
  },
  "SOME-API-KEY-VALUE-2": {
    "permissions": 2,
    "path": "/files-2/",
    "expiration_date": "0001-01-01T00:00:00Z"
  }
}

Example: Query Specific API Key

type ApiKeyInfo struct {
    Value          string    `json:"value"`
    Permissions    string    `json:"permissions"`
    Path           string    `json:"path"`
    ExpirationDate time.Time `json:"expiration_date"`
    CreatedAt      time.Time `json:"created_at"`
}
func QueryApiKeyInfo(value string) ApiKeyInfo {
  var key ApiKeyInfo
  url := fmt.Sprintf("%s/api-key?value=%s", SHARD_NODE_URL, url.QueryEscape(value))
  req, err := http.NewRequest(http.MethodGet, url, nil)
  if err != nil {
      panic(fmt.Errorf("could not create a request to query api key: %w", err))
  }
  req.Header.Set("x-user-api-key", ADMIN_API_KEY)

  client := http.DefaultClient
  resp, err := client.Do(req)
  if err != nil {
      panic(fmt.Errorf("could not do a request to query api key: %w", err))
  }
  defer resp.Body.Close()

  if resp.StatusCode != http.StatusOK {
      body, _ := io.ReadAll(resp.Body)
      panic(fmt.Sprintf("Query key failed with status %d: %s", resp.StatusCode, string(body)))
  }

  if err := json.NewDecoder(resp.Body).Decode(&key); err != nil {
      panic(fmt.Errorf("could not decode json from server: %w", err))
  }
  return key
}
interface ApiKeyInfo {
    value: string;
    permissions: string;
    path: string;
    expiration_date: string;
    created_at: string;
}

async function queryApiKeyInfo(value: string): Promise<ApiKeyInfo> {
    const url = `${SHARD_NODE_URL}/api-key?value=${encodeURIComponent(value)}`;
    const res = await fetch(url, {
        method: 'GET',
        headers: { 'x-user-api-key': ADMIN_API_KEY }
    });

    if (res.status !== 200) {
        const body = await res.text();
        throw new Error(`Query key failed with status ${res.status}: ${body}`);
    }

    const key: ApiKeyInfo = await res.json();
    return key;
}

Example: Query All API Keys

func QueryApiKeysInfo() map[string]ApiKeyInfo {
    keys := map[string]ApiKeyInfo{}
    url := fmt.Sprintf("%s/api-key", SHARD_NODE_URL)
    req, err := http.NewRequest(http.MethodGet, url, nil)
    if err != nil {
        panic(fmt.Errorf("could not create a request to query api keys: %w", err))
    }
    req.Header.Set("x-user-api-key", ADMIN_API_KEY)

    client := http.DefaultClient
    resp, err := client.Do(req)
    if err != nil {
        panic(fmt.Errorf("could not do a request to query api keys: %w", err))
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        body, _ := io.ReadAll(resp.Body)
        panic(fmt.Sprintf("Query keys failed with status %d: %s", resp.StatusCode, string(body)))
    }

    if err := json.NewDecoder(resp.Body).Decode(&keys); err != nil {
        panic(fmt.Errorf("could not decode json from server: %w", err))
    }
    return keys
}
async function queryApiKeysInfo(): Promise<Record<string, ApiKeyInfo>> {
    const url = `${SHARD_NODE_URL}/api-key`;
    const res = await fetch(url, {
        method: 'GET',
        headers: { 'x-user-api-key': ADMIN_API_KEY }
    });

    if (res.status !== 200) {
        const body = await res.text();
        throw new Error(`Query keys failed with status ${res.status}: ${body}`);
    }

    const keys: Record<string, ApiKeyInfo> = await res.json();
    return keys;
}

Response Status Codes

Code Status Description
200 Success API key information retrieved successfully
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing API key
404 Not Found API key not found (when querying specific key)
5xx Server Error Internal server error - check response body for details

Example Response (All Keys)

{
  "api_key_1_value": {
    "value": "api_key_1_value",
    "permissions": 3,
    "path": "/files/",
    "expiration_date": "2025-12-31T23:59:59Z",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "api_key_2_value": {
    "value": "api_key_2_value",
    "permissions": 1,
    "path": "/backup/",
    "expiration_date": "0001-01-01T00:00:00Z",
    "created_at": "2024-02-20T14:45:00Z"
  }
}

Example Response (Single Key)

{
  "value": "api_key_1_value",
  "permissions": 3,
  "path": "/files/",
  "expiration_date": "2025-12-31T23:59:59Z",
  "created_at": "2024-01-15T10:30:00Z"
}