English for WorkOS Developers

WorkOS exists to abstract away the messy details of enterprise identity — SSO, SCIM provisioning, directory sync — but a team integrating it still needs precise vocabulary, because customer IT admins will use these exact terms and expect the engineering team to understand them without translation. This guide covers the English used when discussing WorkOS integrations with a team.

Key Vocabulary

SSO (Single Sign-On) connection — a configured integration between your application and a customer’s identity provider (like Okta or Azure AD), letting their employees log in using their existing corporate credentials. “The customer’s SSO connection is misconfigured on their end — their identity provider is sending the assertion to the wrong callback URL, not something we can fix from our side.”

SAML assertion — the signed XML document an identity provider sends after a successful login, containing the authenticated user’s identity and attributes, which the application must validate before establishing a session. “The login is failing because the SAML assertion’s signature doesn’t validate — that usually means the identity provider’s certificate was rotated and we have a stale one configured.”

SCIM provisioning — an automated protocol for creating, updating, and deactivating user accounts based on changes in a customer’s identity provider, so access is kept in sync without manual admin work. “When an employee leaves the customer’s company, SCIM provisioning should deactivate their account here automatically — if it’s not happening, check whether the SCIM endpoint is actually receiving deprovisioning events.”

Directory sync — the ongoing synchronization of a customer’s user and group directory (departments, roles, memberships) into your application, typically the data source SCIM provisioning is built on. “We’re granting access based on group membership, so directory sync needs to include group data, not just individual user records.”

Identity provider (IdP) vs. service provider (SP) — in an SSO flow, the IdP is the customer’s authentication system (Okta, Azure AD, Google Workspace); the service provider is your application, which trusts assertions issued by the IdP. “From our side as the service provider, we just need to validate the assertion’s signature and audience — the actual login challenge happens entirely on the IdP’s side.”

Connection domain — the email domain(s) associated with an SSO connection, used to route a user attempting to log in to the correct identity provider automatically. “The user is being routed to the wrong SSO connection because their email domain was added to two different connections by mistake — connection domains need to be unique per customer.”

Common Phrases

• “Is this an SSO connection misconfiguration, or an issue on our side as the service provider?”
• “Is the SAML assertion failing to validate, or is it not reaching us at all?”
• “Is SCIM provisioning actually deprovisioning users, or just creating new ones?”
• “Does directory sync include group memberships, or only individual users?”
• “Is this connection domain conflicting with another customer’s SSO setup?”

Example Sentences

Reviewing a pull request: “This webhook handler only processes SCIM ‘create’ events — let’s make sure we’re also handling ‘deactivate’ events, otherwise offboarded employees will keep their access indefinitely.”

Explaining a design decision: “We built access control on top of directory sync group data instead of individual user attributes, so a customer’s own org structure changes automatically flow through to our permissions.”

Describing a bug: “Enterprise users couldn’t log in after their IT team rotated their identity provider’s signing certificate — we were still validating against the old one.”

Professional Tips

• Say “SSO connection” and “SCIM provisioning” as the precise, customer-facing terms — enterprise IT admins use this exact vocabulary, and matching it builds credibility in support conversations.
• When debugging login failures, ask “is this an assertion validation problem or a routing problem?” — these point to different parts of the SSO flow.
• Use “identity provider” and “service provider” correctly — your application is the service provider trusting the customer’s identity provider, not the other way around.
• Distinguish “directory sync” (the underlying data feed) from “SCIM provisioning” (the automated account lifecycle actions built on that data) when explaining an offboarding gap.

Practice Exercise

1. Explain in two sentences the difference between an identity provider and a service provider in an SSO flow.
2. Write a one-sentence explanation of what SCIM provisioning is for, aimed at a non-technical stakeholder.
3. Describe, in your own words, why a stale identity provider certificate would cause SAML assertion validation to fail.

Navigating Nuance: Addressing Feedback & Collaboration

For non-native speakers, the subtleties of professional English in a technical environment can feel particularly challenging. It’s not just about knowing the definition of words like “provisioning” or “authentication”; it’s about understanding how those terms are used within conversations, code reviews, and documentation – and crucially, how to respond effectively. A key difference often lies in the implicit expectations surrounding collaboration. Developers frequently use phrasing that conveys levels of urgency, responsibility, and constructive criticism. Recognizing these nuances is vital for smooth integration into a team.

Let’s consider a scenario: You’ve been reviewing a PR submitted by a colleague, Mark, focused on integrating a new SCIM provider. The code review comment reads: “This looks good overall, but could we add some error handling around the user_attribute_mapping configuration? It’s currently very permissive and might lead to unexpected data updates if the SCIM provider returns invalid values.” Mark hasn’t explicitly stated a problem; he’s framed it as a potential risk. A direct translation of “invalid values” might not fully capture the concern. Instead, Mark is communicating a need for robustness and proactive mitigation. It’s a gentle but firm suggestion to improve the code’s resilience. Similarly, in Slack, a message like “Can someone double-check this provisioning flow? I’m seeing some inconsistencies with user groups” isn’t simply pointing out an error; it’s requesting verification – a collaborative effort to ensure accuracy and prevent future problems. Learning to interpret these indirect requests and responding with clear, actionable feedback is essential. Don’t just say “Fixed.” Explain why you made the change and what steps were taken to address the underlying issue.

Furthermore, phrasing related to prioritization can be tricky. Saying something like “This needs to be fixed ASAP” can sound demanding. A better approach might be: “Let’s prioritize this alongside the SSO rollout – ensuring a seamless user experience is paramount.” The latter conveys urgency without sounding aggressive and focuses on the bigger picture. Understanding that many technical discussions involve trade-offs—balancing security, performance, and development time—is also crucial. This often manifests in requests for clarification: “Can you elaborate on the potential impact of this change on directory sync latency?” – a question designed to assess risk and inform decision-making.

# Example CLI command using WorkOS's `workos` CLI (hypothetical, but representative)
workos scim user update --user-id 1234567890 --attribute "email" --value "new.email@example.com" --fields email

This simple command illustrates how technical vocabulary – update, user-id, attribute, value – are used in a practical context when interacting with WorkOS’s SCIM functionality. It’s important to recognize that even seemingly straightforward commands require precise language and understanding of the underlying processes.