{"id":18321117,"url":"https://github.com/workos/workos-kotlin","last_synced_at":"2026-05-06T03:02:26.795Z","repository":{"id":37896473,"uuid":"419780611","full_name":"workos/workos-kotlin","owner":"workos","description":"Official Kotlin SDK for interacting with the WorkOS API","archived":false,"fork":false,"pushed_at":"2026-04-30T13:16:34.000Z","size":1408,"stargazers_count":18,"open_issues_count":16,"forks_count":9,"subscribers_count":16,"default_branch":"main","last_synced_at":"2026-04-30T14:23:12.866Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","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":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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":"2021-10-21T15:35:32.000Z","updated_at":"2026-04-30T13:16:56.000Z","dependencies_parsed_at":"2025-11-21T08:01:37.559Z","dependency_job_id":null,"html_url":"https://github.com/workos/workos-kotlin","commit_stats":null,"previous_names":[],"tags_count":66,"template":false,"template_full_name":null,"purl":"pkg:github/workos/workos-kotlin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fworkos-kotlin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fworkos-kotlin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fworkos-kotlin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fworkos-kotlin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/workos","download_url":"https://codeload.github.com/workos/workos-kotlin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workos%2Fworkos-kotlin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32676510,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T02:33:58.958Z","status":"ssl_error","status_checked_at":"2026-05-06T02:33:39.611Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2024-11-05T18:18:26.066Z","updated_at":"2026-05-06T03:02:26.786Z","avatar_url":"https://github.com/workos.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WorkOS Kotlin [![Maven Central](https://img.shields.io/maven-central/v/com.workos/workos.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.workos%22%20AND%20a:%22workos%22)\n\nThe WorkOS Kotlin library provides convenient access to the WorkOS API from applications written in JVM-compatible languages (Kotlin, Java, Scala, etc.).\n\n## Documentation\n\nSee the [API Reference](https://workos.com/docs/reference/client-libraries) for Kotlin/Java usage examples.\nSee the [v5 migration guide](./docs/V5_MIGRATION_GUIDE.md) when upgrading from the pre-generated SDK surface.\n\n## Installation\n\nReplace `VERSION` in the snippets below with the latest release from [Maven Central](https://search.maven.org/artifact/com.workos/workos).\n\n### Apache Maven\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.workos\u003c/groupId\u003e\n  \u003cartifactId\u003eworkos\u003c/artifactId\u003e\n  \u003cversion\u003eVERSION\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### Gradle (Groovy DSL)\n\n```groovy\ndependencies {\n  implementation 'com.workos:workos:VERSION'\n}\n```\n\n### Gradle (Kotlin DSL)\n\n```kotlin\ndependencies {\n  implementation(\"com.workos:workos:VERSION\")\n}\n```\n\n## Compatibility\n\n- JDK 17+\n- Kotlin 2.1.x or newer\n\n## Configuration\n\nConstruct a `WorkOS` client by passing your API key. All other parameters are optional.\n\n```kotlin\nimport com.workos.WorkOS\nimport com.workos.common.http.RetryConfig\n\nval workos = WorkOS(\n  apiKey = System.getenv(\"WORKOS_API_KEY\"),\n  // Required for several user-management auth flows (token exchange, etc.)\n  clientId = System.getenv(\"WORKOS_CLIENT_ID\"),\n  // Defaults to \"https://api.workos.com\". Override for staging or proxies.\n  apiBaseUrl = \"https://api.workos.com\",\n  // Optional — defaults to a 30s-timeout OkHttpClient.\n  // httpClient = myCustomOkHttpClient,\n  // Retry/backoff policy. Defaults to exponential backoff with 3 retries.\n  retryConfig = RetryConfig.DEFAULT,\n)\n```\n\n| Parameter     | Required | Description                                                       |\n| ------------- | -------- | ----------------------------------------------------------------- |\n| `apiKey`      | yes      | WorkOS secret key (`sk_*`).                                       |\n| `clientId`    | no       | Required for user-management auth flows and public-client usage.  |\n| `apiBaseUrl`  | no       | Defaults to `https://api.workos.com`. Override for staging/local. |\n| `httpClient`  | no       | Bring-your-own `OkHttpClient` for telemetry, interceptors, etc.   |\n| `retryConfig` | no       | See `RetryConfig.DEFAULT` / `RetryConfig.DISABLED`.               |\n\n### Java usage\n\nService accessors are regular properties on the `WorkOS` class, so they work natively from Java:\n\n```java\nimport com.workos.WorkOS;\n\nWorkOS workos = new WorkOS(System.getenv(\"WORKOS_API_KEY\"));\nworkos.getUserManagement().list();\n```\n\nFor more configurable construction, `WorkOS.builder()` exposes a fluent\nbuilder so Java callers can set only the parameters they care about:\n\n```java\nimport com.workos.WorkOS;\nimport com.workos.common.http.RetryConfig;\n\nWorkOS workos = WorkOS.builder()\n    .apiKey(System.getenv(\"WORKOS_API_KEY\"))\n    .clientId(System.getenv(\"WORKOS_CLIENT_ID\"))\n    .retryConfig(RetryConfig.DISABLED)\n    .build();\n```\n\nGenerated model and exception properties are exposed as Kotlin `val`s with\n`@JvmField`, which means Java callers read them as fields rather than\nthrough bean-style getters — `connection.id`, not `connection.getId()`.\nSealed-class operation parameters (e.g. `ResourceTarget`) include\nJava-friendly overloads that take the discriminating fields directly\n(`workos.getAuthorization().checkByExternalId(...)`) so you do not have to\nconstruct the variant class explicitly.\n\n## Service accessors\n\nOnce constructed, every WorkOS API surface is available as a property on the `WorkOS` instance.\n\n### Authentication and identity\n\n- `workos.sso`\n- `workos.userManagement`\n- `workos.userManagementOrganizationMembershipGroups`\n- `workos.passwordless` †\n- `workos.multiFactorAuth`\n\n### Organizations and directories\n\n- `workos.organizations`\n- `workos.organizationDomains`\n- `workos.directorySync`\n- `workos.groups`\n\n### Authorization and access control\n\n- `workos.authorization`\n- `workos.featureFlags`\n\n### Observability and compliance\n\n- `workos.auditLogs`\n- `workos.events`\n- `workos.webhooks`\n- `workos.radar`\n\n### Integrations and tooling\n\n- `workos.connect`\n- `workos.pipes`\n- `workos.widgets`\n- `workos.apiKeys`\n- `workos.adminPortal`\n- `workos.actions` †\n- `workos.vault` †\n\n† Provided as a Kotlin extension property. From Java, access these via the\ngenerated static accessor on the corresponding `*Kt` file\n(e.g. `PasswordlessKt.getPasswordless(workos)`) instead of as a member of\n`WorkOS`.\n\n## Quickstart examples\n\n```kotlin\nimport com.workos.WorkOS\n\nval workos = WorkOS(System.getenv(\"WORKOS_API_KEY\"))\n\nval org = workos.organizations.create(\n  name = \"Foo Corp\",\n)\nprintln(\"Created ${org.id}\")\n\n// Auto-paginate through every event, one page at a time.\nval events = workos.events.list(events = listOf(\"dsync.user.created\"))\nfor (event in events.autoPagingIterable()) {\n  println(event.id)\n}\n```\n\n## Error handling\n\nEvery API error deserializes into a typed subclass of\n`com.workos.common.exceptions.WorkOSException`:\n\n| HTTP status | Exception                                                   |\n| ----------- | ----------------------------------------------------------- |\n| 400         | `com.workos.common.exceptions.BadRequestException`          |\n| 401         | `com.workos.common.exceptions.UnauthorizedException`        |\n| 404         | `com.workos.common.exceptions.NotFoundException`            |\n| 422         | `com.workos.common.exceptions.UnprocessableEntityException` |\n| 429         | `com.workos.common.exceptions.RateLimitException`           |\n| 5xx         | `com.workos.common.exceptions.GenericServerException`       |\n| other       | `com.workos.common.exceptions.WorkOSGenericException`       |\n| transport   | `com.workos.common.exceptions.TransportException`           |\n\n`TransportException` (status `0`) is thrown when the SDK cannot reach the\nAPI at all — IOExceptions, timeouts, DNS or TLS failures.\n`WorkOSGenericException` is thrown when the API returns an HTTP status the\nSDK does not have a more specific exception type for.\n\nEach exception exposes the response `code`, human-readable `message`, and\nthe structured `errors: List\u003cApiError\u003e?` array returned by the API.\n`ApiError` is a typed model (`field`, `code`, `message`) so callers can\ninspect validation failures without `Map` casts.\n`RateLimitException` additionally exposes `retryAfterSeconds` parsed from\nthe `Retry-After` response header (delta-seconds or HTTP-date) when the\nserver provides one. `WorkOSException.rawBody` also preserves the raw HTTP\nresponse body for debugging; treat it as sensitive because it can contain\nPII or secrets that should be redacted before logging.\n\n```kotlin\nimport com.workos.common.exceptions.NotFoundException\n\ntry {\n  workos.organizations.get(\"org_nope\")\n} catch (e: NotFoundException) {\n  println(\"Not found: ${e.message}\")\n}\n```\n\n## Webhook signatures\n\nThe standalone `Webhook` helper validates signatures on inbound webhook\npayloads. Two flavors are available:\n\n- `constructTypedEvent(...)` returns a sealed `WorkOSEvent` you can\n  pattern-match against — preferred for the common case.\n- `constructEvent(...)` returns a raw `JsonNode`, which is useful if you\n  need to handle event types the SDK does not yet model.\n\n```kotlin\nimport com.workos.models.WorkOSEvent\nimport com.workos.webhooks.Webhook\n\nval event = Webhook().constructTypedEvent(\n  payload = rawRequestBody,\n  signatureHeader = request.getHeader(\"WorkOS-Signature\"),\n  secret = System.getenv(\"WORKOS_WEBHOOK_SECRET\"),\n)\n\nwhen (event) {\n  is WorkOSEvent.UserCreated -\u003e println(\"New user ${event.data.id}\")\n  else -\u003e println(\"Other event ${event.event}\")\n}\n```\n\n## PATCH semantics\n\nPATCH endpoints distinguish between \"field omitted\", \"field set to a\nvalue\", and \"field explicitly cleared to `null`\". Use `PatchField` to\nexpress that intent — see the\n[v5 migration guide](./docs/V5_MIGRATION_GUIDE.md#8-patch-semantics-use-patchfield)\nfor examples.\n\n## Coroutines\n\nEvery generated service method has both a blocking version and a\ncoroutine-aware `\u003cmethod\u003eSuspend` variant that wraps the call in\n`withContext(Dispatchers.IO)`. Add `kotlinx-coroutines-core` to your\nclasspath (already a transitive dependency of this SDK) and call from any\n`suspend` context:\n\n```kotlin\nval org = workos.organizations.createSuspend(name = \"Foo Corp\")\n\nval firstPage = workos.organizations.listSuspend(limit = 10)\nfor (org in firstPage.data) println(org.id)\n```\n\nThe blocking and suspend forms are independently named (`create` vs\n`createSuspend`) so they can coexist on the same service without Kotlin\noverload-resolution ambiguity.\n\n## Pagination\n\nAll `list(...)` methods return a `Page\u003cT\u003e`. You can either consume a single\npage directly, or walk every page via the auto-paging iterator.\n\n```kotlin\nval firstPage = workos.organizations.list(limit = 10)\nfor (org in firstPage.data) println(org.id)\n\n// Walk the full result set.\nfor (org in firstPage.autoPagingIterable()) println(org.id)\n```\n\n## Per-request options\n\nEvery generated method accepts an optional `RequestOptions` argument for\nper-call overrides:\n\n```kotlin\nimport com.workos.common.http.RequestOptions\n\nworkos.organizations.create(\n  name = \"Foo Corp\",\n  requestOptions =\n    RequestOptions.builder()\n      .idempotencyKey(java.util.UUID.randomUUID().toString())\n      .maxRetries(0)\n      .build(),\n)\n```\n\n## Unknown enum values\n\nGenerated enums include an `Unknown` variant annotated with Jackson's\n`@JsonEnumDefaultValue`. When the API introduces a new wire value the SDK\nhas not yet been updated for, deserialization falls back to `Unknown`\ninstead of throwing. Callers that need to preserve the raw value should\ninspect the underlying JSON directly until the SDK is regenerated.\n\n## SDK versioning\n\nThis SDK follows [SemVer](https://semver.org/). Breaking changes only ship\nin major releases — read the changelog before upgrading across a major\nversion boundary.\n\n## More information\n\n- [Single Sign-On Guide](https://workos.com/docs/sso/guide)\n- [Directory Sync Guide](https://workos.com/docs/directory-sync/guide)\n- [User Management](https://workos.com/docs/user-management/guide)\n- [Admin Portal Guide](https://workos.com/docs/admin-portal/guide)\n- [Magic Link Guide](https://workos.com/docs/magic-link/guide)\n- [Example applications](https://github.com/workos-inc/java-example-applications)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkos%2Fworkos-kotlin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fworkos%2Fworkos-kotlin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkos%2Fworkos-kotlin/lists"}