{"id":50999026,"url":"https://github.com/workos/workos-rust","last_synced_at":"2026-06-20T12:34:23.833Z","repository":{"id":357456464,"uuid":"482870836","full_name":"workos/workos-rust","owner":"workos","description":"Official Rust SDK for interacting with the WorkOS API","archived":false,"fork":false,"pushed_at":"2026-06-17T01:55:22.000Z","size":22597,"stargazers_count":12,"open_issues_count":4,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-06-17T03:23:52.430Z","etag":null,"topics":["backend","sdk"],"latest_commit_sha":null,"homepage":"https://workos.github.io/workos-rust/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/workos.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-04-18T14:10:45.000Z","updated_at":"2026-06-17T01:55:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/workos/workos-rust","commit_stats":null,"previous_names":["workos/workos-rust"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/workos/workos-rust","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fworkos-rust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fworkos-rust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fworkos-rust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fworkos-rust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/workos","download_url":"https://codeload.github.com/workos/workos-rust/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fworkos-rust/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34570538,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backend","sdk"],"created_at":"2026-06-20T12:34:23.241Z","updated_at":"2026-06-20T12:34:23.818Z","avatar_url":"https://github.com/workos.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WorkOS Rust Library\n\nThe WorkOS Rust SDK provides async access to the WorkOS API from Rust applications. It uses `tokio`, ships with a default `reqwest` HTTP transport, and includes helpers for common WorkOS flows such as AuthKit, SSO, webhooks, sessions, JWKS, PKCE, and Vault local crypto.\n\n## Documentation\n\n- [WorkOS API Reference](https://workos.com/docs/reference)\n- [Crate docs on docs.rs](https://docs.rs/workos)\n- [Changelog](./CHANGELOG.md)\n\n## Installation\n\nRequires Rust `1.88+` (edition 2024). The repository pins this via `rust-toolchain.toml`, so a fresh checkout will install the matching toolchain automatically when you run any `cargo` or `./script/ci` command under `rustup`.\n\n```bash\ncargo add workos\n```\n\nBy default, the crate enables `reqwest` with `rustls-tls`. You can switch TLS backends or provide a custom HTTP transport; see [HTTP Transport](#http-transport).\n\n## Quick Start\n\n```rust\nuse workos::{Client, organizations::ListOrganizationsParams};\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), workos::Error\u003e {\n    let client = Client::builder()\n        .api_key(std::env::var(\"WORKOS_API_KEY\").unwrap())\n        .client_id(std::env::var(\"WORKOS_CLIENT_ID\").unwrap())\n        .build();\n\n    let page = client\n        .organizations()\n        .list_organizations(ListOrganizationsParams::default())\n        .await?;\n\n    for org in page.data {\n        println!(\"{}: {}\", org.id, org.name);\n    }\n\n    Ok(())\n}\n```\n\nFor an API-key-only client with default settings:\n\n```rust\nlet client = workos::Client::new(std::env::var(\"WORKOS_API_KEY\").unwrap());\n```\n\n## Configuration\n\n`Client::builder()` supports:\n\n| Method            | Description                                                         |\n| ----------------- | ------------------------------------------------------------------- |\n| `.api_key(_)`     | WorkOS secret key (`sk_...`), required for authenticated API calls. |\n| `.client_id(_)`   | WorkOS Client ID, required for AuthKit, SSO, and JWKS helpers.      |\n| `.base_url(_)`    | Override the API host. Defaults to `https://api.workos.com`.        |\n| `.timeout(_)`     | Per-request timeout. Defaults to 30 seconds.                        |\n| `.max_retries(_)` | Retry budget for `429` and `5xx` responses. Defaults to 3.          |\n| `.user_agent(_)`  | Override the `User-Agent` header.                                   |\n| `.transport(_)`   | Plug in a custom `HttpTransport`.                                   |\n\n`build()` panics if the supplied API key or user-agent contains bytes that aren't valid in an HTTP header. Use `.try_build()` to surface those failures as `Err(workos::Error::Builder(_))` instead — useful when the API key comes from untrusted input.\n\nThe client is cheap to clone and can be shared across handlers and tasks.\n\n## API Access\n\nAPI resources are exposed as accessors on `Client`, for example:\n\n```rust\nclient.organizations();\nclient.user_management();\nclient.sso();\nclient.webhooks();\nclient.audit_logs();\n```\n\nList endpoints return `Page\u003cT\u003e` values with `data` and `list_metadata` cursors. The crate also exports `auto_paginate` for stream-based iteration.\n\nEvery API call returns `Result\u003c_, workos::Error\u003e`. The error type includes API errors, transport failures, decode errors, configuration errors, and helper-specific failures. It also provides predicates such as `is_unauthorized()`, `is_not_found()`, `is_rate_limited()`, and `is_server_error()`.\n\nSee the [crate docs](https://docs.rs/workos) for the full resource list, request and response types, pagination details, and helper APIs.\n\n### Forward-compatible enums\n\nGenerated enums are `#[non_exhaustive]` and include an `Unknown(String)` variant for wire values the SDK doesn't recognize yet — WorkOS can add new enum values server-side without breaking deserialization for older SDK builds. Match defensively:\n\n```rust\nuse workos::ConnectionType;\n\nmatch connection.r#type {\n    ConnectionType::GoogleOAuth =\u003e { /* ... */ }\n    ConnectionType::Unknown(raw) =\u003e {\n        log::warn!(\"unknown connection type: {raw}\");\n    }\n    _ =\u003e { /* ... */ }\n}\n```\n\nThe original wire string is preserved through round-trips: serializing an `Unknown(\"FooBar\")` re-emits `\"FooBar\"` verbatim. Each enum also implements `Display`, `FromStr` (infallible), and `AsRef\u003cstr\u003e` for ergonomic conversions.\n\n## Per-Request Options\n\nEach generated method has a `*_with_options` companion that takes a `RequestOptions`. Use it to pass an idempotency key, additional headers, or a per-request retry policy:\n\n```rust\nuse workos::{RequestOptions, organizations::CreateOrganizationParams};\n\nlet opts = RequestOptions::new().idempotency_key(\"ik_create_acme_42\");\n\nlet org = client\n    .organizations()\n    .create_organization_with_options(\n        CreateOrganizationParams::new(workos::OrganizationInput {\n            name: \"Acme\".into(),\n            ..Default::default()\n        }),\n        Some(\u0026opts),\n    )\n    .await?;\n```\n\nReplaying a mutating request with the same idempotency key is safe; WorkOS recognises the key on the server side.\n\n### Request strategies\n\nFor finer-grained control, attach a `RequestStrategy` to override the client's default retry behavior on a single call:\n\n```rust\nuse workos::{RequestOptions, RequestStrategy};\n\n// Send exactly once, regardless of `max_retries`:\nlet opts = RequestOptions::new().strategy(RequestStrategy::Once);\n\n// Make a mutation idempotent and retry-eligible (the key is also sent\n// as the `Idempotency-Key` header):\nlet opts = RequestOptions::new()\n    .strategy(RequestStrategy::Idempotent(\"ik_42\".into()));\n\n// Custom retry budget with jitter:\nlet opts = RequestOptions::new().strategy(RequestStrategy::ExponentialBackoff {\n    max_attempts: 5,\n    jitter: true,\n});\n```\n\nVariants: `Once`, `Idempotent(key)`, `Retry { max_attempts }`, `ExponentialBackoff { max_attempts, jitter }`.\n\n## Errors\n\nAPI errors carry structured metadata. Always log `request_id()` when reporting bugs to WorkOS:\n\n```rust\nmatch client.organizations().get_organization(\"org_missing\").await {\n    Ok(org) =\u003e println!(\"{org:?}\"),\n    Err(err) if err.is_not_found() =\u003e println!(\"not found\"),\n    Err(err) =\u003e {\n        eprintln!(\n            \"API error {} (code={:?}, request_id={:?}): {}\",\n            err.status().unwrap_or(0),\n            err.code(),\n            err.request_id(),\n            err.api().map(|a| a.message.as_str()).unwrap_or(\"\"),\n        );\n        if let Some(after) = err.retry_after() {\n            eprintln!(\"retry after {after:?}\");\n        }\n    }\n}\n```\n\n`err.api()` returns the full `ApiError` with the raw response headers and body for advanced debugging.\n\n## Sensitive Fields\n\nFields that hold credentials or tokens — `password`, `client_secret`, `access_token`, `refresh_token`, `token`, `secret`, etc. — are typed as `workos::SecretString`. Their `Debug` representation prints `\"\u003credacted\u003e\"`, so secrets don't leak through logs, panic messages, or error reports. Read the underlying value with `.expose()` when you genuinely need it:\n\n```rust\nlet token: \u0026str = session.access_token.expose();\n```\n\n`SecretString` serializes transparently as a JSON string, so the wire format is unchanged. Constructors that accept a sensitive parameter take `impl Into\u003cSecretString\u003e` — passing a `String` or `\u0026str` works without an explicit conversion.\n\n## Retries\n\nThe client retries `429` and `5xx` responses (plus retryable transport errors) up to `max_retries` times — default `3` — with exponential backoff and equal-jitter. The `Retry-After` header is honored when present and supersedes the computed backoff.\n\nTo preserve at-most-once semantics for state-changing calls, only safe HTTP methods (`GET`/`HEAD`/`OPTIONS`) and requests carrying an `Idempotency-Key` are auto-retried. POST/PUT/PATCH/DELETE without an idempotency key are sent exactly once.\n\n```rust\n// Disable retries entirely for this client:\nlet client = workos::Client::builder()\n    .api_key(std::env::var(\"WORKOS_API_KEY\").unwrap())\n    .max_retries(0)\n    .build();\n```\n\nPair mutations with an idempotency key (or `RequestStrategy::Idempotent`) so a redelivered request is processed exactly once on the server.\n\n## Auto-Paging\n\nEvery list endpoint generates a `*_auto_paging` companion that returns a `futures_util::Stream`, advancing the `after` cursor under the hood:\n\n```rust\nuse futures_util::TryStreamExt;\nuse workos::organizations::ListOrganizationsParams;\n\nlet all: Vec\u003cworkos::Organization\u003e = client\n    .organizations()\n    .list_organizations_auto_paging(ListOrganizationsParams::default())\n    .try_collect()\n    .await?;\n```\n\nFor custom paginated flows the crate also re-exports the lower-level `auto_paginate(fetch)` helper, which drives any `(after) -\u003e Result\u003cPage\u003cT\u003e, _\u003e` closure to exhaustion.\n\n## Helpers\n\nThe SDK includes hand-maintained helpers for:\n\n- AuthKit and SSO URL builders, PKCE flows, token exchange, logout, and device authorization.\n- Webhook signature verification.\n- Sealed session cookies.\n- JWKS fetching and URL construction.\n- Vault key-value operations and optional local AES-GCM encryption.\n- Public PKCE-only clients for browser or mobile flows that must not hold an API key.\n\n## HTTP Transport\n\nThe default HTTP transport is `reqwest`, gated behind the default `reqwest` feature. To use another client, share an existing request pipeline, or support environments such as WASM, disable default features and provide a `workos::transport::HttpTransport` implementation:\n\n```toml\n# Cargo.toml\nworkos = { version = \"1\", default-features = false }\n```\n\n```rust\nlet transport: workos::transport::SharedTransport = std::sync::Arc::new(MyTransport);\n\nlet client = workos::Client::builder()\n    .api_key(\"sk_...\")\n    .transport(transport)\n    .build();\n```\n\nSupported crate features:\n\n| Feature      | Default | Description                                           |\n| ------------ | ------- | ----------------------------------------------------- |\n| `reqwest`    | yes     | Enables the bundled `reqwest` transport.              |\n| `rustls-tls` | yes     | Uses `rustls` for TLS through `reqwest`.              |\n| `native-tls` | no      | Uses the platform native TLS stack through `reqwest`. |\n\n## More Information\n\n- [WorkOS Docs](https://workos.com/docs)\n- [API Reference](https://workos.com/docs/reference)\n- [Issues](https://github.com/workos/workos-rust/issues)\n\n## License\n\nMIT. See [LICENSE.txt](./LICENSE.txt).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkos%2Fworkos-rust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fworkos%2Fworkos-rust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkos%2Fworkos-rust/lists"}