Struct Client

Source

pub struct Client { /* private fields */ }

Expand description

Truthlinked Authority Fabric API client

Provides type-safe access to the Truthlinked Authority Fabric API with enterprise-grade security and reliability features.

§Security Features

HTTPS-only communication (HTTP requests are rejected)
TLS certificate validation (no self-signed certificates)
License key memory protection (zeroized on drop)
Safe error handling (no credential leakage)
Connection pooling with reasonable limits
Request timeouts to prevent hanging

§Thread Safety

This client is Send + Sync and can be safely shared across threads. Consider using Arc<Client> for shared access.

§Example

use truthlinked_sdk::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new(
        "https://api.truthlinked.org",
        std::env::var("TRUTHLINKED_LICENSE_KEY")?
    )?;
     
    let health = client.health().await?;
    println!("Server status: {}", health.status);
    Ok(())
}

Implementations§

Source §

impl Client

Source

pub fn new( base_url: impl Into<String>, license_key: impl Into<String>, ) -> Result<Self>

Creates a new Truthlinked API client

§Arguments

base_url - API base URL (must be HTTPS)
license_key - Your Truthlinked license key

§Security Guarantees

Enforces HTTPS only (HTTP requests are rejected at client creation)
Uses rustls TLS implementation (no OpenSSL vulnerabilities)
Validates TLS certificates (rejects self-signed certificates)
Configures reasonable timeouts (prevents indefinite hanging)
Enables connection pooling (improves performance and reliability)

§Errors

Returns TruthlinkedError::InvalidRequest if:

Base URL does not start with “https://”
HTTP client cannot be configured

§Example

use truthlinked_sdk::Client;
 
let client = Client::new(
    "https://api.truthlinked.org",
    "tl_free_..."
)?;

Source

pub async fn health(&self) -> Result<HealthResponse>

Performs a health check against the Truthlinked API

This endpoint does not require authentication and can be used to verify that the API is accessible and responding correctly.

§Returns

Ok(HealthResponse) - Server is healthy and responding
Err(TruthlinkedError) - Network error or server unavailable

§Example

let health = client.health().await?;
assert_eq!(health.status, "healthy");

Source

pub async fn exchange_token( &self, sso_token: impl Into<String>, requested_scope: Vec<String>, nonce: [u8; 32], channel_binding: [u8; 32], ) -> Result<TokenResponse>

Exchanges an SSO token for an Authority Fabric token

This operation requires a Professional tier license or higher. The SSO token is validated and, if successful, an AF token is issued with the requested scope (potentially narrowed based on policy).

§Arguments

sso_token - Valid SSO token from your identity provider
requested_scope - List of permissions requested (e.g., [“read:users”])
nonce - 32-byte cryptographic nonce (prevents replay attacks)
channel_binding - 32-byte channel binding (prevents MITM attacks)

§Security Notes

Nonce must be cryptographically random and unique per request
Channel binding should be derived from the TLS channel
The granted scope may be narrower than requested based on policy

§Errors

Unauthorized - Invalid license key or SSO token
Forbidden - License tier doesn’t support token exchange
InvalidRequest - Malformed request parameters

§Example

use rand::Rng;
 
let nonce: [u8; 32] = rand::thread_rng().gen();
let channel_binding: [u8; 32] = rand::thread_rng().gen();
 
let response = client.exchange_token(
    "eyJ0eXAiOiJKV1QiLCJhbGc...",
    vec!["read:users".to_string()],
    nonce,
    channel_binding,
).await?;
 
println!("AF Token: {}", response.af_token);

Source

pub async fn validate_token( &self, token_id: impl Into<String>, ) -> Result<ValidateResponse>

Validate AF token

Source

pub async fn get_shadow_decisions(&self) -> Result<Vec<ShadowDecision>>

Retrieves shadow decisions showing breach prevention activity

Shadow mode runs your IAM decisions through the Authority Fabric policy engine in parallel, identifying cases where IAM would have allowed access but AF would have denied it (indicating a potential security breach).

This endpoint is available to all license tiers.

§Returns

A list of shadow decisions, where each decision represents a divergence between IAM and AF policy evaluation. Decisions with breach_prevented: true indicate cases where AF would have prevented a security breach.

§Example

let decisions = client.get_shadow_decisions().await?;
 
let breaches_prevented = decisions.iter()
    .filter(|d| d.breach_prevented)
    .count();
 
println!("Breaches prevented: {}", breaches_prevented);

Source