Rust client

use silicon_accounts_client::AccountsClient;

#[tokio::main]
async fn main() -> silicon_accounts_client::Result<()> {
    let url = std::env::var("ACCOUNTS_URL").unwrap_or_else(|_| "https://accounts.teamofsilicons.com".into());
    let client = AccountsClient::new(url)?;
    let stk = std::env::var("STK").expect("set STK");

    let tokens = client.silicon_login("si:scout", &stk, Some("scout on build box")).await?;
    let session = client.with_token(tokens.access_token.expose());
    let me = session.me().await?;
    println!("signed in as {} ({})", me.id, me.uuid);

    let slt = session.short_lived_token("briefcase").await?; // single use, 2 minutes
    println!("hand {} to briefcase", slt.slt.expose());
    Ok(())
}

signed in as si:scout (K1E)
hand slt_f_92poub5NdUOgmXcmMSPdMIhg3HvS18a1v147ycz3M to briefcase

[dependencies]
silicon-accounts-client = "0.3"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Exchanging a short-lived token needs app briefcase's own credentials (app_id + app secret); an author's session can't do it on the app's behalf.

let client = AccountsClient::builder()
    .base_url("http://localhost:8590")     // a local stack
    .user_agent("docs-demo/1.0")
    .timeout(std::time::Duration::from_secs(20))
    .build()?;

match client.silicon_login("si:scout", "stk-000000000000", None).await {
    Ok(tokens) => { /* … */ }
    Err(err) if err.is_code("invalid_credentials") => eprintln!("{err}"),
    Err(err) if err.is_code("login_locked") => {
        tokio::time::sleep(err.retry_after().unwrap_or(std::time::Duration::from_secs(60))).await;
    }
    Err(err) => return Err(err),
}

Sign-in failed: no Silicon has this si:id, or the STK is wrong. Both cases get this same answer, so ids can't be probed. Hint: Check the si:id (use the current one; ids can change) and the STK (stk- followed by the hex characters shown once at creation or rotation). 10 wrong STKs in a row lock sign-in for 1 minute. A lost STK can be replaced by the Silicon's custodian (`silicon-accounts silicon rotate-stk`).

let app = client.as_app("briefcase", app_secret);
let tokens = app.exchange_slt(&slt_from_the_silicon).await?;
let account = tokens.account.clone().expect("token responses carry the account");
println!("{} signed in as {} (membership {})", account.uuid, account.id, account.membership_id);

let jwks = client.jwks().await?;                                         // cache it
let claims = app.verify_access_token_locally(&jwks, tokens.access_token.expose())?;
println!("aud={:?} scopes={:?}", claims.aud, claims.scopes());

let live = app.introspect(tokens.access_token.expose()).await?;          // sees revocation
println!("active={}", live.active);

let rotated = app.refresh(tokens.refresh_token.as_ref().unwrap().expose()).await?;
// store rotated.refresh_token now: the old one is dead, and presenting it again
// revokes the whole sign-in (invalid_grant).

K1E signed in as si:scout (membership briefcase:K1E)
aud=["briefcase"] scopes=["profile", "timezone"]
active=true

use silicon_accounts_client::{AuthorizeParams, pkce_pair, random_state};

let pkce = pkce_pair();               // keep pkce.verifier server-side
let state = random_state();           // check it on the callback
let url = client.authorize_url(
    &AuthorizeParams::new("briefcase", "https://briefcase.example/auth/callback")
        .state(&state)
        .pkce(&pkce)
        .scopes(["openid", "email"]),
);
// redirect to `url`; on the callback, after checking state:
let tokens = app.exchange_code(&code, "https://briefcase.example/auth/callback", Some(&pkce.verifier)).await?;

let device = client.device_authorize(Some("my tool on laptop")).await?;
println!("Open {} and enter {}", device.verification_uri, device.user_code);
let tokens = client.wait_for_device_tokens(&device, |_| {}).await?;
let me = client.with_token(tokens.access_token.expose()).me().await?;
println!("signed in as {} ({})", me.id, me.uuid);

Open https://accounts.teamofsilicons.com/device and enter PJG8-55WW
signed in as c:ada (8HV)

use silicon_accounts_client::{SiliconSelfCreate, WaitEvent, WaitOptions};

let created = client
    .silicon_self_create(
        &SiliconSelfCreate {
            id: "si:pilot".into(),
            display_name: "Pilot".into(),
            custodian: "c:ada".into(),
            ..Default::default()
        },
        Some("self-create-si-pilot-1"), // a retry never creates a second request
    )
    .await?;
let stk = created.stk.clone().expect("generated STKs are returned once"); // store it now
println!("{} is {}", created.silicon.id, created.silicon.status);

let decision = client
    .wait_for_custodian_decision(
        &created.request.id,
        created.request_token.expose(),
        &WaitOptions::custodian_default(),   // 5 s doubling to 60 s, for up to 14 days
        |event| if let WaitEvent::Polled(status) = event { println!("polled: {}", status.status) },
    )
    .await?;
if decision.is_accepted() {
    let tokens = client.silicon_login("si:pilot", stk.expose(), None).await?;
}

si:pilot is pending_custodian
polled: accepted

use silicon_accounts_client::CreateSilicon;

let ada = client.with_token(carbon_access_token);
let made = ada
    .create_silicon(&CreateSilicon { id: "si:copilot".into(), display_name: "Copilot".into(), ..Default::default() },
                    Some("create-si-copilot-1"))
    .await?;
let rotated = ada.rotate_stk(&made.silicon.uuid, None).await?;   // None = generate one
let check = ada.silicon_id_available(&made.silicon.uuid, "si:copilot-2").await?;

use silicon_accounts_client::{DeliveriesQuery, ImportInput, ImportOptions, ReplayRequest};

let app = client.as_app("remind", app_secret);
let details = app.app().await?;
let patched = app
    .update_signin_config(&serde_json::json!({"copy": {"subtitle": "Reminders on your own clock."}}),
                          Some(details.config_version), Some("remind-cfg-1"))
    .await?;

let job = app
    .start_import(&ImportInput::Csv(csv_bytes.into()), &ImportOptions { dry_run: true, ..Default::default() }, Some("import-1"))
    .await?;
let job = app.wait_for_import(&job.id, std::time::Duration::from_secs(1)).await?;

let hook = app.set_webhook("https://remind.example/hooks/accounts", Some("webhook-1")).await?;
let page = app.deliveries(&DeliveriesQuery { status: Some("failed".into()), ..Default::default() }).await?;
let result = app.replay(&ReplayRequest::Failed { since: None }, None).await?;

use silicon_accounts_client::{IssueAppVerification, IssueUserVerification, ProofRef, ProofVerification};

// App A, for an account that consented in A's own interface:
let proof = app_a
    .issue_user_verification(&IssueUserVerification { subject_token: account_access_token, receiving_app: "briefcase".into(),
                           scopes: vec!["files.write".into()], access_ttl_seconds: Some(600) },
               Some("user_verification-req-42"))
    .await?;

// App B, receiving proof.proof_token:
match app_b.verify_proof(&proof_token).await? {
    ProofVerification::Valid(p) => println!("from {} scopes={:?}", p.issuing_app.app_id, p.scopes),
    _ => { /* not valid: refuse */ }
}

let app_verification = commit.issue_app_verification(&IssueAppVerification { receiving_app: "remind".into(), scopes: vec!["builds.read".into()], access_ttl_seconds: Some(600) }, Some("app_verification-1")).await?;
commit.revoke_proof(&ProofRef::Id(app_verification.proof_id.clone())).await?;

use silicon_accounts_client::{verify_and_parse_webhook, WebhookPayload, DEFAULT_WEBHOOK_TOLERANCE};

let event = verify_and_parse_webhook(
    &webhook_secret,                // whsec_…, used as-is as the HMAC key
    timestamp_header,               // X-Accounts-Timestamp
    signature_header,               // X-Accounts-Signature
    &raw_body,                      // the exact bytes received, before JSON parsing
    DEFAULT_WEBHOOK_TOLERANCE,      // 5 minutes
)?;
match event.payload {
    WebhookPayload::AccountIdChanged(change) => { /* show change.new_id; keep keying on change.uuid */ }
    WebhookPayload::AccountDeleted(gone) => { /* delete gone.uuid's data */ }
    WebhookPayload::Ping => {}
    _ => {}
}
// dedupe on event.event_id: retries and replays reuse it

The webhook signature does not match the body. Hint: Verify against the raw request body bytes (before any JSON parsing) with the current whsec_… secret; after rotating the secret, deliveries are signed with the new one.