WorkOSClient is the server-side Swift client used from trusted backend code to call WorkOS APIs with an API key. It is designed for application servers, functions, and shared backend packages, not for client applications. The client exposes typed resources for organizations, users, directories, and other API objects.
What WorkOSClient Is Built For
WorkOSClient is a server-side Swift client for trusted backend code. It is meant to call WorkOS APIs with an API key from application servers, functions, or shared backend packages, not from client applications.
That design matters because the client is a backend integration surface, not a user-facing SDK. Its purpose is to let server code safely reach WorkOS resources such as organizations, users, and directories with typed access to API objects.
Why the Server-Side Boundary Matters
The key distinction is where the code runs. A backend client can keep secrets on the server, while a client application cannot be trusted with an API key. That separation is what makes the client suitable for server-side use and unsuitable for browser, mobile, or other untrusted environments.
This boundary also shapes how you think about trust: the client is only as safe as the runtime that hosts it. If the backend is compromised, the API key and any WorkOS actions available to that key can be abused through the same integration path.
What the Typed Resources Represent
WorkOSClient exposes typed resources for common API objects so backend code can work with organizations, users, directories, and related concepts in a structured way. Typed resources reduce ambiguity in application code and make integrations easier to read, maintain, and test.
That structure is especially useful when a server must map WorkOS data into its own account, tenancy, or directory logic. The client becomes the programmatic bridge between your application model and the WorkOS API surface.
How to Use It Correctly in Backend Architecture
Use WorkOSClient only where the server can protect credentials and enforce its own authorization checks before making WorkOS calls. In practice, that means the client belongs in controlled backend services, serverless functions, or shared server libraries that are never shipped to the end user.
It is also important to treat the API key as privileged configuration rather than application data. The client can simplify backend integration, but it does not remove the need to restrict access, rotate secrets, and keep WorkOS operations inside trusted server-side boundaries.
Risk and Threat Considerations
Using a server-side API client with an exposed or misused key creates direct access risk. If the key leaks, or if the client is embedded in an untrusted environment, an attacker can often call the same API surface the backend uses and potentially enumerate or modify tenant and directory data.
Failure mechanism: The security model fails when backend-only credentials are placed in client code, logged, copied into insecure build artifacts, or used from a runtime that attackers can inspect or tamper with.
Impact: Unauthorized API calls can lead to account, organization, or directory exposure, unexpected administrative actions, and broader trust failure in the integration path.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
OWASP API Security Top 10 addresses the attack and risk surface, while NIST SP 800-53 Rev 5, NIST CSF 2.0, OWASP ASVS and CIS Controls v8 set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| NIST SP 800-53 Rev 5 | IA-5 — Authenticator Management | Server-side API key use depends on secure credential lifecycle and protection. |
| AC-6 — Least Privilege | Backend access should be limited to only the WorkOS actions needed by the service. | |
| SC-13 — Cryptographic Protection | Trusted-server integrations rely on protected secret material and secure transport. | |
| Recommendation — Protect and rotate the WorkOS API key as an authenticator under IA-5. Limit the backend identity and API key to the minimum WorkOS permissions needed. Use SC-13 to protect API key handling and transmitted credentials in backend integrations. | ||
| OWASP API Security Top 10 | API2 — Broken Authentication | The client authenticates to WorkOS APIs using an API key and must not be exposed to untrusted runtimes. |
| API8 — Security Misconfiguration | Putting a server client or API key into the wrong runtime is a configuration flaw. | |
| Recommendation — Keep the API key server-side so WorkOS authentication cannot be broken by client exposure. Prevent misconfiguration by restricting WorkOSClient to trusted backend environments. | ||
| NIST CSF 2.0 | PR.AA-05 — Least Privilege | The backend integration should have only the access needed to call WorkOS APIs. |
| Recommendation — Constrain backend access paths and secrets to the minimum required for WorkOS calls. | ||
| OWASP ASVS | V13 — Configuration | Server-only secret placement and deployment boundaries are configuration concerns in application security. |
| V14 — Data Protection | API keys and API responses must be protected as sensitive data in transit and at rest. | |
| Recommendation — Verify that WorkOSClient and its API key are never delivered to client-side deployments. Protect WorkOS credentials and returned identity data under V14 controls. | ||
| CIS Controls v8 | CIS-5 — Account Management | The client’s API-key-backed access should be governed like privileged account material. |
| Recommendation — Govern backend access to WorkOS with controlled account and secret management practices. | ||
Practitioner Guidance
Why practitioners should care: The main decision is not how to call the API, but where to allow the call to originate. WorkOSClient should stay inside trusted server execution paths so the API key remains off the client and the application can keep control over authorization and secret handling.
What to watch for: Any attempt to reuse the client in browser code, ship the API key in frontend bundles, or expose it through logs and environment leakage should be treated as an architectural defect rather than a convenience tradeoff.
