Rust SDK

vaultaris-sdk is a typed, async Rust client for the Vaultaris API. It handles token management, automatic refresh, and optional DPoP sender-constrained tokens (RFC 9449).

Open SDKs. The SDKs are developed in the open at github.com/Vaultaris/sdk — issues, PRs and feedback welcome.

Installation

[dependencies]
vaultaris-sdk = { path = "../crates/vaultaris-sdk" }
tokio = { version = "1", features = ["full"] }

Basic setup

use vaultaris_sdk::{VaultarisClient, ClientConfig};

let client = VaultarisClient::new(ClientConfig {
    base_url: "https://auth.example.com".to_string(),
    client_id: "my-service".to_string(),
    client_secret: Some("secret".to_string()),
    tenant_id: "your-tenant-uuid".parse()?,
});

// Authenticate (client credentials grant)
let token = client.authenticate().await?;

DPoP — Sender-Constrained Tokens

Pass a DpopSigner to bind all issued tokens to your key pair. The SDK generates fresh DPoP proofs automatically on every request.

use vaultaris_sdk::{VaultarisClient, ClientConfig, DpopSigner};

// Generate a new ed25519 key pair for this service instance
let signer = DpopSigner::generate_ed25519()?;

let client = VaultarisClient::builder()
    .config(ClientConfig { ... })
    .dpop_signer(signer)
    .build();

// All token requests and API calls include the DPoP header automatically
let token = client.authenticate().await?;

To use an HSM or external KMS for key storage, implement the DpopSigner trait:

pub trait DpopSigner: Send + Sync {
    fn public_key_jwk(&self) -> serde_json::Value;
    async fn sign(&self, payload: &[u8]) -> Result<Vec<u8>, DpopSignerError>;
}

Token management

The SDK manages token refresh automatically. Tokens are refreshed proactively before expiry.

// Manual token operations
let token = client.token()
    .scopes(["openid", "profile"])
    .send()
    .await?;

let info = client.introspect(&token.access_token).await?;
println!("expires: {}", info.exp);

User management

use vaultaris_sdk::dto::CreateUserRequest;

let user = client.users().create(CreateUserRequest {
    email: "alice@example.com".to_string(),
    password: Some("strong-pass".to_string()),
    first_name: Some("Alice".to_string()),
    last_name: Some("Admin".to_string()),
    ..Default::default()
}).await?;

// Assign a role
client.users().assign_role(user.id, role_id).await?;

// List users (paginated)
let page = client.users().list().page(1).per_page(50).send().await?;

Session validation

// Validate a global session token from another domain
let result = client.sessions()
    .validate_global("gst_xxxxxxxxxx", "app.example.com")
    .await?;

if result.valid {
    println!("user_id: {}", result.user_id);
}

API key authorization

// RBAC + ABAC authorization decision
let decision = client.api_keys()
    .authorize("documents", "write", json!({ "doc_owner": user_id }))
    .await?;

if decision.allowed {
    // proceed
}

Error handling

use vaultaris_sdk::Error;

match client.users().get(user_id).await {
    Ok(user) => { /* ... */ }
    Err(Error::NotFound) => { /* 404 */ }
    Err(Error::Unauthorized) => { /* 401 — refresh token expired */ }
    Err(Error::RateLimited { retry_after }) => { /* 429 */ }
    Err(e) => return Err(e.into()),
}

Plugin development

To build a Vaultaris plugin, use the vaultaris-plugin-sdk crate. See Plugins for the full SDK reference including the DpopSigner trait for HSM-backed key storage.