SDKs

Arcan provides official client SDKs for Go, Python, and Node.js. All SDKs have zero external dependencies and use only standard library modules.

Install

Go

go get getarcan.dev/arcan/sdk/go

Python

pip install arcan

Requires Python 3.8+.

Node.js

npm install @getarcan/sdk

Requires Node.js 18+.

Quick Start

Go

package main

import (
    "fmt"
    "log"

    arcan "getarcan.dev/arcan/sdk/go"
)

func main() {
    client, err := arcan.New(
        arcan.WithURL("https://arcan.internal:9797"),
        arcan.WithToken("arc_xxx"),
        arcan.WithRealm("production"),
        arcan.WithEnv("prod"),
    )
    if err != nil {
        log.Fatal(err)
    }

    dbURL, err := client.Get("DATABASE_URL")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(dbURL)
}

Python

from arcan import ArcanClient

client = ArcanClient(
    url="https://arcan.internal:9797",
    token="arc_xxx",
    realm="production",
    env="prod",
)
db_url = client.get("DATABASE_URL")

Node.js

import { ArcanClient } from '@getarcan/sdk';

const client = new ArcanClient({
  url: 'https://arcan.internal:9797',
  token: 'arc_xxx',
  realm: 'production',
  env: 'prod',
});

const dbUrl = await client.get('DATABASE_URL');

Environment Variable Auto-Config

All SDKs support automatic configuration from environment variables. Set ARCAN_URL, ARCAN_TOKEN, ARCAN_REALM, and ARCAN_ENV, then create a client with no arguments:

Go

client, err := arcan.New()
if err != nil {
    log.Fatal(err)
}
dbURL := client.MustGet("DATABASE_URL")

Python

client = ArcanClient()
db_url = client.get("DATABASE_URL")

Node.js

const client = new ArcanClient();
const dbUrl = await client.get('DATABASE_URL');

API Reference

Client Options

Go

Option	Default	Description
WithURL(url)	ARCAN_URL or https://localhost:9797	Server URL
WithToken(token)	ARCAN_TOKEN	Auth token (required)
WithRealm(realm)	ARCAN_REALM or "default"	Realm/namespace
WithEnv(env)	ARCAN_ENV or "dev"	Environment
WithInsecureSkipVerify(bool)	true	Accept self-signed certs
WithCacheTTL(duration)	5m	Cache TTL (0 to disable)

Python

Parameter	Default	Description
url	ARCAN_URL or https://localhost:9797	Server URL
token	ARCAN_TOKEN	Auth token (required)
realm	ARCAN_REALM or "default"	Realm/namespace
env	ARCAN_ENV or "dev"	Environment
verify_ssl	False	Verify TLS certificates
cache_ttl	300	Cache TTL in seconds (0 = disabled)

Node.js

Option	Default	Description
url	ARCAN_URL or https://localhost:9797	Server URL
token	ARCAN_TOKEN	Auth token (required)
realm	ARCAN_REALM or "default"	Realm/namespace
env	ARCAN_ENV or "dev"	Environment
rejectUnauthorized	false	Reject invalid TLS certs
cacheTtlMs	300000	Cache TTL in ms (0 = disabled)

Methods

All SDKs provide the same core methods:

Method	Description
Get(key) / get(key)	Fetch a secret value
GetWithMeta(key) / get_meta(key) / getMeta(key)	Fetch secret with metadata
List() / list()	Fetch all secrets
Set(key, value) / set(key, value)	Create or update a secret
Delete(key) / delete(key)	Delete a secret
Health() / health()	Check server health

Go additionally has MustGet(key) which panics on error (useful for initialization).

Error Handling

Go

import "errors"

val, err := client.Get("MY_SECRET")
if errors.Is(err, arcan.ErrNotFound) {
    // Secret does not exist
} else if errors.Is(err, arcan.ErrAuth) {
    // Invalid or expired token
} else if errors.Is(err, arcan.ErrConnection) {
    // Cannot reach server
} else if errors.Is(err, arcan.ErrServer) {
    // Server returned 5xx
}

Python

from arcan import ArcanClient, NotFoundError, AuthError, ConnectionError, ServerError

try:
    val = client.get("MY_SECRET")
except NotFoundError:
    print("Secret does not exist")
except AuthError:
    print("Invalid or expired token")
except ConnectionError:
    print("Cannot reach Arcan server")
except ServerError:
    print("Server returned an error")

Node.js

import {
  ArcanClient,
  NotFoundError,
  AuthError,
  ConnectionError,
  ServerError,
} from '@getarcan/sdk';

try {
  const val = await client.get('MY_SECRET');
} catch (err) {
  if (err instanceof NotFoundError) {
    // Secret does not exist
  } else if (err instanceof AuthError) {
    // Invalid or expired token
  } else if (err instanceof ConnectionError) {
    // Cannot reach server
  } else if (err instanceof ServerError) {
    // Server returned 5xx
  }
}

Caching

All SDKs cache secrets in memory for 5 minutes by default. The cache is thread-safe. Write operations (Set, Delete) automatically invalidate relevant cache entries.

Go

// Disable caching
client, _ := arcan.New(arcan.WithCacheTTL(0))

// Cache for 30 seconds
client, _ := arcan.New(arcan.WithCacheTTL(30 * time.Second))

Python

# Disable caching
client = ArcanClient(token="arc_xxx", cache_ttl=0)

# Cache for 30 seconds
client = ArcanClient(token="arc_xxx", cache_ttl=30)

Node.js

// Disable caching
const client = new ArcanClient({ token: 'arc_xxx', cacheTtlMs: 0 });

// Cache for 30 seconds
const client = new ArcanClient({ token: 'arc_xxx', cacheTtlMs: 30_000 });

Security

• Use valid TLS certificates in production (not self-signed)
• Store API tokens in your platform's secret management (not hardcoded)
• Use read-only tokens (arcan token create --scopes read) for applications that only need to read secrets
• Enable audit logging on the Arcan server to track all secret access