# Directory Structure ``` ├── .cursor │ └── rules │ └── mcp.mdc ├── .gitignore ├── biome.json ├── bun.lock ├── docs.md ├── LICENSE ├── package.json ├── patches │ └── [email protected] ├── README.md ├── src │ ├── index.ts │ ├── utils.ts │ └── workos │ ├── events.ts │ ├── memberships.ts │ ├── organizations.ts │ ├── roles.ts │ └── users.ts ├── tsconfig.json ├── worker-configuration.d.ts └── wrangler.jsonc ``` # Files -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- ``` 1 | .DS_Store 2 | node_modules/ 3 | .dev.vars 4 | dist/ 5 | secrets.json 6 | .wrangler/ ``` -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- ```markdown 1 | # workos-mcp 2 | 3 | This is a lightweight Model Control Protocol (MCP) server bootstrapped with [create-mcp](https://github.com/zueai/create-mcp), and deployed on Cloudflare Workers. 4 | 5 | This MCP Server allows agents (like Cursor Agents) to interact with the [WorkOS API](https://workos.com/docs/reference). 6 | 7 | ## Available Tools 8 | 9 | See [src/index.ts](src/index.ts) for the current list of tools. Every method in the class is an MCP tool. 10 | 11 | ## Installation 12 | 13 | 1. Run the automated install script to clone this MCP server and deploy it to your Cloudflare account: 14 | 15 | ```bash 16 | bun create mcp --clone https://github.com/zueai/workos-mcp 17 | ``` 18 | 19 | 2. Open `Cursor Settings -> MCP -> Add new MCP server` and paste the command that was copied to your clipboard. 20 | 21 | 3. Upload your WorkOS API key and client ID as secrets: 22 | 23 | ```bash 24 | bunx wrangler secret put WORKOS_API_KEY 25 | bunx wrangler secret put WORKOS_CLIENT_ID 26 | ``` 27 | 28 | ## Deploying Changes 29 | 30 | 1. Run the deploy script: 31 | 32 | ```bash 33 | bun run deploy 34 | ``` 35 | 36 | 2. Then reload your Cursor window to use the updated tools. 37 | 38 | ## How to create new MCP tools 39 | 40 | To create new MCP tools, add methods to the `MyWorker` class in `src/index.ts`. Each function will automatically become an MCP tool that your agent can use. 41 | 42 | Example: 43 | 44 | ```typescript 45 | /** 46 | * A warm, friendly greeting from your MCP server. 47 | * @param name {string} the name of the person we are greeting. 48 | * @return {string} the contents of our greeting. 49 | */ 50 | sayHello(name: string) { 51 | return `Hello from an MCP Worker, ${name}!`; 52 | } 53 | ``` 54 | 55 | The JSDoc comments are important: 56 | 57 | - First line becomes the tool's description 58 | - `@param` tags define the tool's parameters with types and descriptions 59 | - `@return` tag specifies the return value and type 60 | 61 | ## Learn More 62 | 63 | Check out the following resources to learn more: 64 | 65 | - [create-mcp Documentation](https://github.com/zueai/create-mcp) - learn about the create-mcp CLI 66 | - [Model Control Protocol Documentation](https://modelcontextprotocol.io) - learn about the model control protocol 67 | - [workers-mcp](https://github.com/cloudflare/workers-mcp) - the package that implements the MCP protocol for Cloudflare Workers 68 | - [Cloudflare Workers documentation](https://developers.cloudflare.com/workers/) - learn about the Cloudflare Workers platform 69 | - [WorkOS Documentation](https://workos.com/docs) - learn about the WorkOS API 70 | ``` -------------------------------------------------------------------------------- /worker-configuration.d.ts: -------------------------------------------------------------------------------- ```typescript 1 | // Generated by Wrangler by running `wrangler types` 2 | 3 | interface Env { 4 | SHARED_SECRET: string; 5 | WORKOS_API_KEY: string; 6 | WORKOS_CLIENT_ID: string; 7 | } 8 | ``` -------------------------------------------------------------------------------- /src/utils.ts: -------------------------------------------------------------------------------- ```typescript 1 | import { WorkOS } from "@workos-inc/node" 2 | 3 | export function MCPResponse(data: unknown) { 4 | return { 5 | content: [{ type: "text", text: JSON.stringify(data, null, 2) }] 6 | } 7 | } 8 | 9 | export function getWorkOSClient(env: Env) { 10 | return new WorkOS(env.WORKOS_API_KEY, { 11 | clientId: env.WORKOS_CLIENT_ID 12 | }) 13 | } 14 | ``` -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- ```json 1 | { 2 | "compilerOptions": { 3 | "target": "ESNext", 4 | "module": "ESNext", 5 | "moduleResolution": "Bundler", 6 | "strict": true, 7 | "skipLibCheck": true, 8 | "lib": ["ESNext"], 9 | "types": ["@cloudflare/workers-types/2023-07-01"], 10 | "jsx": "react-jsx", 11 | "jsxImportSource": "hono/jsx", 12 | "baseUrl": ".", 13 | "paths": { 14 | "@/*": ["./src/*"] 15 | } 16 | }, 17 | "include": ["src/**/*", "worker-configuration.d.ts"] 18 | } 19 | ``` -------------------------------------------------------------------------------- /src/workos/roles.ts: -------------------------------------------------------------------------------- ```typescript 1 | import { MCPResponse, getWorkOSClient } from "../utils" 2 | 3 | export async function listOrganizationRoles( 4 | env: Env, 5 | organizationId: string, 6 | limit?: number, 7 | after?: string, 8 | before?: string 9 | ) { 10 | const workos = getWorkOSClient(env) 11 | 12 | const options = { 13 | organizationId, 14 | limit, 15 | after, 16 | before 17 | } 18 | 19 | const roles = await workos.organizations.listOrganizationRoles(options) 20 | 21 | return MCPResponse(roles) 22 | } 23 | ``` -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- ```json 1 | { 2 | "name": "workos-mcp", 3 | "scripts": { 4 | "dev": "bun check && wrangler dev", 5 | "deploy": "workers-mcp docgen src/index.ts && bun check && wrangler deploy --minify", 6 | "check": "bunx biome check --write .", 7 | "secrets": "wrangler secret bulk secrets.json" 8 | }, 9 | "dependencies": { 10 | "@workos-inc/node": "^7.39.0", 11 | "workers-mcp": "^0.0.13" 12 | }, 13 | "devDependencies": { 14 | "@biomejs/biome": "^1.9.4", 15 | "@cloudflare/workers-types": "^4.20250109.0", 16 | "wrangler": "^3.101.0" 17 | }, 18 | "patchedDependencies": { 19 | "[email protected]": "patches/[email protected]" 20 | } 21 | } 22 | ``` -------------------------------------------------------------------------------- /biome.json: -------------------------------------------------------------------------------- ```json 1 | { 2 | "files": { 3 | "ignore": [ 4 | "dist/**/*", 5 | "node_modules/**/*", 6 | "public/**/*", 7 | "**/*.css", 8 | ".wrangler/**/*", 9 | "drizzle/**/*", 10 | "worker-configuration.d.ts" 11 | ] 12 | }, 13 | "linter": { 14 | "enabled": true, 15 | "rules": { 16 | "recommended": true 17 | }, 18 | "ignore": [ 19 | "**/*.md", 20 | "**/*.css", 21 | ".wrangler/**/*", 22 | "node_modules/**/*", 23 | "drizzle/**/*", 24 | "worker-configuration.d.ts" 25 | ] 26 | }, 27 | "formatter": { 28 | "enabled": true, 29 | "indentStyle": "tab", 30 | "indentWidth": 4 31 | }, 32 | "javascript": { 33 | "formatter": { 34 | "semicolons": "asNeeded", 35 | "trailingCommas": "none" 36 | } 37 | }, 38 | "json": { 39 | "parser": { 40 | "allowComments": true 41 | } 42 | } 43 | } 44 | ``` -------------------------------------------------------------------------------- /src/workos/events.ts: -------------------------------------------------------------------------------- ```typescript 1 | import type { EventName } from "@workos-inc/node" 2 | import { MCPResponse, getWorkOSClient } from "../utils" 3 | 4 | export async function listEvents( 5 | env: Env, 6 | events: EventName[], 7 | rangeStart?: string, 8 | rangeEnd?: string, 9 | limit?: number, 10 | after?: string, 11 | organizationId?: string 12 | ) { 13 | const workos = getWorkOSClient(env) 14 | 15 | const options: { 16 | events: EventName[] 17 | rangeStart?: string 18 | rangeEnd?: string 19 | limit?: number 20 | after?: string 21 | organizationId?: string 22 | } = { 23 | events 24 | } 25 | 26 | if (rangeStart) options.rangeStart = rangeStart 27 | if (rangeEnd) options.rangeEnd = rangeEnd 28 | if (limit) options.limit = limit 29 | if (after) options.after = after 30 | if (organizationId) options.organizationId = organizationId 31 | 32 | const listOfEvents = await workos.events.listEvents(options) 33 | 34 | return MCPResponse(listOfEvents) 35 | } 36 | ``` -------------------------------------------------------------------------------- /src/workos/organizations.ts: -------------------------------------------------------------------------------- ```typescript 1 | import type { 2 | CreateOrganizationOptions, 3 | CreateOrganizationRequestOptions, 4 | ListOrganizationsOptions, 5 | UpdateOrganizationOptions 6 | } from "@workos-inc/node" 7 | import { MCPResponse, getWorkOSClient } from "../utils" 8 | 9 | export async function listOrganizations( 10 | env: Env, 11 | domains?: string[], 12 | limit?: number, 13 | before?: string, 14 | after?: string 15 | ) { 16 | const workos = getWorkOSClient(env) 17 | 18 | const options: ListOrganizationsOptions = {} 19 | if (domains) options.domains = domains 20 | if (limit) options.limit = limit 21 | if (before) options.before = before 22 | if (after) options.after = after 23 | 24 | const organizations = await workos.organizations.listOrganizations(options) 25 | 26 | return MCPResponse(organizations) 27 | } 28 | 29 | export async function createOrganization( 30 | env: Env, 31 | payload: CreateOrganizationOptions, 32 | requestOptions?: CreateOrganizationRequestOptions 33 | ) { 34 | const workos = getWorkOSClient(env) 35 | 36 | const organization = await workos.organizations.createOrganization( 37 | payload, 38 | requestOptions 39 | ) 40 | 41 | return MCPResponse(organization) 42 | } 43 | 44 | export async function deleteOrganization(env: Env, id: string) { 45 | const workos = getWorkOSClient(env) 46 | 47 | await workos.organizations.deleteOrganization(id) 48 | 49 | return MCPResponse({ success: true, id }) 50 | } 51 | 52 | export async function getOrganization(env: Env, id: string) { 53 | const workos = getWorkOSClient(env) 54 | 55 | const organization = await workos.organizations.getOrganization(id) 56 | 57 | return MCPResponse(organization) 58 | } 59 | 60 | export async function updateOrganization( 61 | env: Env, 62 | options: UpdateOrganizationOptions 63 | ) { 64 | const workos = getWorkOSClient(env) 65 | 66 | const organization = await workos.organizations.updateOrganization(options) 67 | 68 | return MCPResponse(organization) 69 | } 70 | ``` -------------------------------------------------------------------------------- /src/workos/users.ts: -------------------------------------------------------------------------------- ```typescript 1 | import type { 2 | CreateUserOptions, 3 | ListUsersOptions, 4 | UpdateUserOptions 5 | } from "@workos-inc/node" 6 | import { MCPResponse, getWorkOSClient } from "../utils" 7 | 8 | export async function listUsers( 9 | env: Env, 10 | email?: string, 11 | organizationId?: string, 12 | limit?: number, 13 | before?: string, 14 | after?: string 15 | ) { 16 | const workos = getWorkOSClient(env) 17 | 18 | const options: ListUsersOptions = {} 19 | if (email) options.email = email 20 | if (organizationId) options.organizationId = organizationId 21 | if (limit) options.limit = limit 22 | if (before) options.before = before 23 | if (after) options.after = after 24 | 25 | const users = await workos.userManagement.listUsers(options) 26 | 27 | return MCPResponse(users) 28 | } 29 | 30 | export async function getUser(env: Env, userId: string) { 31 | const workos = getWorkOSClient(env) 32 | 33 | const user = await workos.userManagement.getUser(userId) 34 | 35 | return MCPResponse(user) 36 | } 37 | 38 | export async function createUser(env: Env, payload: CreateUserOptions) { 39 | const workos = getWorkOSClient(env) 40 | 41 | const user = await workos.userManagement.createUser(payload) 42 | 43 | return MCPResponse(user) 44 | } 45 | 46 | export async function updateUser(env: Env, options: UpdateUserOptions) { 47 | const workos = getWorkOSClient(env) 48 | 49 | const user = await workos.userManagement.updateUser(options) 50 | 51 | return MCPResponse(user) 52 | } 53 | 54 | export async function deleteUser(env: Env, userId: string) { 55 | const workos = getWorkOSClient(env) 56 | 57 | await workos.userManagement.deleteUser(userId) 58 | 59 | return MCPResponse({ success: true, id: userId }) 60 | } 61 | 62 | export async function listIdentities(env: Env, userId: string) { 63 | const workos = getWorkOSClient(env) 64 | 65 | const identities = await workos.userManagement.getUserIdentities(userId) 66 | 67 | return MCPResponse(identities) 68 | } 69 | ``` -------------------------------------------------------------------------------- /src/workos/memberships.ts: -------------------------------------------------------------------------------- ```typescript 1 | import type { 2 | CreateOrganizationMembershipOptions, 3 | ListOrganizationMembershipsOptions, 4 | OrganizationMembershipStatus, 5 | UpdateOrganizationMembershipOptions 6 | } from "@workos-inc/node" 7 | import { MCPResponse, getWorkOSClient } from "../utils" 8 | 9 | export async function getOrganizationMembership( 10 | env: Env, 11 | membershipId: string 12 | ) { 13 | const workos = getWorkOSClient(env) 14 | 15 | const membership = 16 | await workos.userManagement.getOrganizationMembership(membershipId) 17 | 18 | return MCPResponse(membership) 19 | } 20 | 21 | export async function listOrganizationMemberships( 22 | env: Env, 23 | organizationId?: string, 24 | userId?: string, 25 | statuses?: string[], 26 | limit?: number, 27 | before?: string, 28 | after?: string 29 | ) { 30 | const workos = getWorkOSClient(env) 31 | 32 | const options: ListOrganizationMembershipsOptions = {} 33 | if (organizationId) options.organizationId = organizationId 34 | if (userId) options.userId = userId 35 | if (statuses) options.statuses = statuses as OrganizationMembershipStatus[] 36 | if (limit) options.limit = limit 37 | if (before) options.before = before 38 | if (after) options.after = after 39 | 40 | const memberships = 41 | await workos.userManagement.listOrganizationMemberships(options) 42 | 43 | return MCPResponse(memberships) 44 | } 45 | 46 | export async function createOrganizationMembership( 47 | env: Env, 48 | options: CreateOrganizationMembershipOptions 49 | ) { 50 | const workos = getWorkOSClient(env) 51 | 52 | const membership = 53 | await workos.userManagement.createOrganizationMembership(options) 54 | 55 | return MCPResponse(membership) 56 | } 57 | 58 | export async function updateOrganizationMembership( 59 | env: Env, 60 | membershipId: string, 61 | options: UpdateOrganizationMembershipOptions 62 | ) { 63 | const workos = getWorkOSClient(env) 64 | 65 | const membership = await workos.userManagement.updateOrganizationMembership( 66 | membershipId, 67 | options 68 | ) 69 | 70 | return MCPResponse(membership) 71 | } 72 | 73 | export async function deleteOrganizationMembership( 74 | env: Env, 75 | membershipId: string 76 | ) { 77 | const workos = getWorkOSClient(env) 78 | 79 | await workos.userManagement.deleteOrganizationMembership(membershipId) 80 | 81 | return MCPResponse({ success: true, id: membershipId }) 82 | } 83 | 84 | export async function deactivateOrganizationMembership( 85 | env: Env, 86 | membershipId: string 87 | ) { 88 | const workos = getWorkOSClient(env) 89 | 90 | const membership = 91 | await workos.userManagement.deactivateOrganizationMembership( 92 | membershipId 93 | ) 94 | 95 | return MCPResponse(membership) 96 | } 97 | 98 | export async function reactivateOrganizationMembership( 99 | env: Env, 100 | membershipId: string 101 | ) { 102 | const workos = getWorkOSClient(env) 103 | 104 | const membership = 105 | await workos.userManagement.reactivateOrganizationMembership( 106 | membershipId 107 | ) 108 | 109 | return MCPResponse(membership) 110 | } 111 | ``` -------------------------------------------------------------------------------- /src/index.ts: -------------------------------------------------------------------------------- ```typescript 1 | import { WorkerEntrypoint } from "cloudflare:workers" 2 | import type { EventName } from "@workos-inc/node" 3 | import type { 4 | CreateOrganizationMembershipOptions, 5 | CreateOrganizationOptions, 6 | CreateOrganizationRequestOptions, 7 | CreateUserOptions, 8 | OrganizationMembershipStatus, 9 | UpdateOrganizationMembershipOptions, 10 | UpdateOrganizationOptions, 11 | UpdateUserOptions 12 | } from "@workos-inc/node" 13 | import { ProxyToSelf } from "workers-mcp" 14 | import { listEvents } from "./workos/events" 15 | import { 16 | createOrganizationMembership, 17 | deactivateOrganizationMembership, 18 | deleteOrganizationMembership, 19 | getOrganizationMembership, 20 | listOrganizationMemberships, 21 | reactivateOrganizationMembership, 22 | updateOrganizationMembership 23 | } from "./workos/memberships" 24 | import { 25 | createOrganization, 26 | deleteOrganization, 27 | getOrganization, 28 | listOrganizations, 29 | updateOrganization 30 | } from "./workos/organizations" 31 | import { listOrganizationRoles } from "./workos/roles" 32 | import { 33 | createUser, 34 | deleteUser, 35 | getUser, 36 | listIdentities, 37 | listUsers, 38 | updateUser 39 | } from "./workos/users" 40 | 41 | export default class MyWorker extends WorkerEntrypoint<Env> { 42 | /** 43 | * @ignore 44 | **/ 45 | async fetch(request: Request): Promise<Response> { 46 | return new ProxyToSelf(this).fetch(request) 47 | } 48 | 49 | /** 50 | * List events from the WorkOS API. 51 | * @param events {string} JSON string array of event types to filter by. Format: ["user.created", "user.deleted"] 52 | * @param rangeStart {string} Optional timestamp to get events from. 53 | * @param rangeEnd {string} Optional timestamp to get events until. 54 | * @param limit {number} Optional limit on number of events to return. 55 | * @param after {string} Optional cursor for pagination. 56 | * @param organizationId {string} Optional organization ID to filter by. 57 | * @return {Promise<any>} List of events matching the criteria. 58 | */ 59 | async listEvents( 60 | events: string, 61 | rangeStart?: string, 62 | rangeEnd?: string, 63 | limit?: number, 64 | after?: string, 65 | organizationId?: string 66 | ) { 67 | // Parse the JSON string to get the array of event types 68 | const parsedEvents = JSON.parse(events) as EventName[] 69 | 70 | return await listEvents( 71 | this.env, 72 | parsedEvents, 73 | rangeStart, 74 | rangeEnd, 75 | limit, 76 | after, 77 | organizationId 78 | ) 79 | } 80 | 81 | /** 82 | * List organizations from the WorkOS API. 83 | * @param domains {string} Optional JSON string array of domains to filter by. Format: ["example.com", "example.org"] 84 | * @param limit {number} Optional limit on number of organizations to return (1-100, default 10). 85 | * @param before {string} Optional cursor for pagination (getting previous results). 86 | * @param after {string} Optional cursor for pagination (getting next results). 87 | * @return {Promise<any>} List of organizations matching the criteria, including pagination metadata and organization objects with the following properties: 88 | * - id {string} - The organization's unique identifier 89 | * - name {string} - The organization's name 90 | * - allowProfilesOutsideOrganization {boolean} - Whether to allow profiles outside the organization 91 | * - domains {Array} - Array of domain objects associated with the organization 92 | * - stripeCustomerId {string|undefined} - Optional Stripe customer ID 93 | * - createdAt {string} - ISO timestamp of creation 94 | * - updatedAt {string} - ISO timestamp of last update 95 | */ 96 | async listOrganizations( 97 | domains?: string, 98 | limit?: number, 99 | before?: string, 100 | after?: string 101 | ) { 102 | // Parse the JSON string to get the array of domains if provided 103 | const parsedDomains = domains 104 | ? (JSON.parse(domains) as string[]) 105 | : undefined 106 | 107 | return await listOrganizations( 108 | this.env, 109 | parsedDomains, 110 | limit, 111 | before, 112 | after 113 | ) 114 | } 115 | 116 | /** 117 | * Create a new organization in WorkOS. 118 | * @param payload {string} JSON string with organization details. Format: 119 | * { 120 | * "name": "Acme Inc.", // Required: The organization's name 121 | * "domains": ["example.com"], // Optional: Array of domains to associate with the organization 122 | * "allowProfilesOutsideOrganization": false, // Optional: Whether to allow profiles outside of the organization (default: false) 123 | * "idempotencyKey": "unique-key-123" // Optional: A unique key to prevent duplicate organizations 124 | * } 125 | * @param requestOptions {string} Optional JSON string with request options. Format: 126 | * { 127 | * "idempotencyKey": "unique-key-123" // Optional: A unique key to prevent duplicate requests 128 | * } 129 | * @return {Promise<any>} The created organization with the following properties: 130 | * - id {string} - The organization's unique identifier 131 | * - name {string} - The organization's name 132 | * - allowProfilesOutsideOrganization {boolean} - Whether profiles outside the organization are allowed 133 | * - domains {Array} - Array of domain objects associated with the organization 134 | * - stripeCustomerId {string|undefined} - Optional Stripe customer ID 135 | * - createdAt {string} - ISO timestamp of creation 136 | * - updatedAt {string} - ISO timestamp of last update 137 | */ 138 | async createOrganization(payload: string, requestOptions?: string) { 139 | // Parse the JSON strings 140 | const parsedPayload = JSON.parse(payload) as CreateOrganizationOptions 141 | const parsedRequestOptions = requestOptions 142 | ? (JSON.parse(requestOptions) as CreateOrganizationRequestOptions) 143 | : undefined 144 | 145 | return await createOrganization( 146 | this.env, 147 | parsedPayload, 148 | parsedRequestOptions 149 | ) 150 | } 151 | 152 | /** 153 | * Delete an organization from WorkOS. 154 | * @param id {string} The ID of the organization to delete (format: "org_..."). 155 | * @return {Promise<any>} Confirmation of deletion with success status and the deleted organization ID. 156 | */ 157 | async deleteOrganization(id: string) { 158 | return await deleteOrganization(this.env, id) 159 | } 160 | 161 | /** 162 | * Get an organization from WorkOS by ID. 163 | * @param id {string} The ID of the organization to retrieve (format: "org_..."). 164 | * @return {Promise<any>} The organization details with the following properties: 165 | * - id {string} - The organization's unique identifier 166 | * - name {string} - The organization's name 167 | * - allowProfilesOutsideOrganization {boolean} - Whether profiles outside the organization are allowed 168 | * - domains {Array} - Array of domain objects associated with the organization 169 | * - stripeCustomerId {string|undefined} - Optional Stripe customer ID 170 | * - createdAt {string} - ISO timestamp of creation 171 | * - updatedAt {string} - ISO timestamp of last update 172 | */ 173 | async getOrganization(id: string) { 174 | return await getOrganization(this.env, id) 175 | } 176 | 177 | /** 178 | * Update an organization in WorkOS. 179 | * @param options {string} JSON string with update options. Format: 180 | * { 181 | * "organizationId": "org_123", // Required: The ID of the organization to update 182 | * "name": "New Name", // Optional: New name for the organization 183 | * "domains": ["new-domain.com"], // Optional: New array of domains (replaces existing domains) 184 | * "allowProfilesOutsideOrganization": true // Optional: Whether to allow profiles outside of the organization 185 | * } 186 | * @return {Promise<any>} The updated organization with the following properties: 187 | * - id {string} - The organization's unique identifier 188 | * - name {string} - The organization's name (updated if changed) 189 | * - allowProfilesOutsideOrganization {boolean} - Whether profiles outside the organization are allowed (updated if changed) 190 | * - domains {Array} - Array of domain objects associated with the organization (updated if changed) 191 | * - stripeCustomerId {string|undefined} - Optional Stripe customer ID 192 | * - createdAt {string} - ISO timestamp of creation 193 | * - updatedAt {string} - ISO timestamp of last update 194 | */ 195 | async updateOrganization(options: string) { 196 | // Parse the JSON string 197 | const parsedOptions = JSON.parse(options) as UpdateOrganizationOptions 198 | 199 | return await updateOrganization(this.env, parsedOptions) 200 | } 201 | 202 | /** 203 | * List roles for an organization in WorkOS. 204 | * @param organizationId {string} The ID of the organization to list roles for (format: "org_..."). 205 | * @param limit {number} Optional limit on number of roles to return (1-100, default 10). 206 | * @param after {string} Optional cursor for pagination (getting next results). 207 | * @param before {string} Optional cursor for pagination (getting previous results). 208 | * @return {Promise<any>} List of roles for the organization, including pagination metadata and role objects with: 209 | * - id {string} - The role's unique identifier 210 | * - name {string} - The role's name 211 | * - description {string} - Description of the role 212 | * - permissions {Array} - Array of permission strings associated with the role 213 | * - createdAt {string} - ISO timestamp of creation 214 | * - updatedAt {string} - ISO timestamp of last update 215 | */ 216 | async listOrganizationRoles( 217 | organizationId: string, 218 | limit?: number, 219 | after?: string, 220 | before?: string 221 | ) { 222 | return await listOrganizationRoles( 223 | this.env, 224 | organizationId, 225 | limit, 226 | after, 227 | before 228 | ) 229 | } 230 | 231 | /** 232 | * List users from the WorkOS API. 233 | * @param email {string} Optional email to filter users by. 234 | * @param organizationId {string} Optional organization ID to filter users by. 235 | * @param limit {number} Optional limit on number of users to return (1-100, default 10). 236 | * @param before {string} Optional cursor for pagination (getting previous results). 237 | * @param after {string} Optional cursor for pagination (getting next results). 238 | * @return {Promise<any>} List of users matching the criteria, including pagination metadata and user objects with: 239 | * - id {string} - The user's unique identifier 240 | * - email {string} - The user's email address 241 | * - emailVerified {boolean} - Whether the email has been verified 242 | * - firstName {string|null} - The user's first name, if provided 243 | * - lastName {string|null} - The user's last name, if provided 244 | * - profilePictureUrl {string|null} - URL to the user's profile picture, if available 245 | * - lastSignInAt {string|null} - ISO timestamp of the user's last sign-in 246 | * - createdAt {string} - ISO timestamp of creation 247 | * - updatedAt {string} - ISO timestamp of last update 248 | */ 249 | async listUsers( 250 | email?: string, 251 | organizationId?: string, 252 | limit?: number, 253 | before?: string, 254 | after?: string 255 | ) { 256 | return await listUsers( 257 | this.env, 258 | email, 259 | organizationId, 260 | limit, 261 | before, 262 | after 263 | ) 264 | } 265 | 266 | /** 267 | * Get a user from the WorkOS API by ID. 268 | * @param userId {string} The ID of the user to retrieve (format: "user_..."). 269 | * @return {Promise<any>} The user details with the following properties: 270 | * - id {string} - The user's unique identifier 271 | * - email {string} - The user's email address 272 | * - emailVerified {boolean} - Whether the email has been verified 273 | * - firstName {string|null} - The user's first name, if provided 274 | * - lastName {string|null} - The user's last name, if provided 275 | * - profilePictureUrl {string|null} - URL to the user's profile picture, if available 276 | * - lastSignInAt {string|null} - ISO timestamp of the user's last sign-in 277 | * - createdAt {string} - ISO timestamp of creation 278 | * - updatedAt {string} - ISO timestamp of last update 279 | */ 280 | async getUser(userId: string) { 281 | return await getUser(this.env, userId) 282 | } 283 | 284 | /** 285 | * Create a new user in WorkOS. 286 | * @param payload {string} JSON string with user details. Format: 287 | * { 288 | * "email": "[email protected]", // Required: The user's email address 289 | * "password": "securepassword", // Optional: Password for the user 290 | * "firstName": "John", // Optional: User's first name 291 | * "lastName": "Doe", // Optional: User's last name 292 | * "emailVerified": true // Optional: Whether the email should be marked as verified (default: false) 293 | * } 294 | * @return {Promise<any>} The created user with the following properties: 295 | * - id {string} - The user's unique identifier 296 | * - email {string} - The user's email address 297 | * - emailVerified {boolean} - Whether the email has been verified 298 | * - firstName {string|null} - The user's first name, if provided 299 | * - lastName {string|null} - The user's last name, if provided 300 | * - profilePictureUrl {string|null} - URL to the user's profile picture, if available 301 | * - lastSignInAt {string|null} - ISO timestamp of the user's last sign-in 302 | * - createdAt {string} - ISO timestamp of creation 303 | * - updatedAt {string} - ISO timestamp of last update 304 | */ 305 | async createUser(payload: string) { 306 | // Parse the JSON string 307 | const parsedPayload = JSON.parse(payload) as CreateUserOptions 308 | 309 | return await createUser(this.env, parsedPayload) 310 | } 311 | 312 | /** 313 | * Update a user in WorkOS. 314 | * @param options {string} JSON string with update options. Format: 315 | * { 316 | * "userId": "user_123", // Required: The ID of the user to update 317 | * "firstName": "New Name", // Optional: New first name for the user 318 | * "lastName": "New Last Name", // Optional: New last name for the user 319 | * "emailVerified": true, // Optional: Whether the email should be marked as verified 320 | * "password": "newpassword" // Optional: New password for the user 321 | * } 322 | * @return {Promise<any>} The updated user with the following properties: 323 | * - id {string} - The user's unique identifier 324 | * - email {string} - The user's email address 325 | * - emailVerified {boolean} - Whether the email has been verified (updated if changed) 326 | * - firstName {string|null} - The user's first name (updated if changed) 327 | * - lastName {string|null} - The user's last name (updated if changed) 328 | * - profilePictureUrl {string|null} - URL to the user's profile picture, if available 329 | * - lastSignInAt {string|null} - ISO timestamp of the user's last sign-in 330 | * - createdAt {string} - ISO timestamp of creation 331 | * - updatedAt {string} - ISO timestamp of last update 332 | */ 333 | async updateUser(options: string) { 334 | // Parse the JSON string 335 | const parsedOptions = JSON.parse(options) as UpdateUserOptions 336 | 337 | return await updateUser(this.env, parsedOptions) 338 | } 339 | 340 | /** 341 | * Delete a user from WorkOS. 342 | * @param userId {string} The ID of the user to delete (format: "user_..."). 343 | * @return {Promise<any>} Confirmation of deletion with success status and the deleted user ID. 344 | */ 345 | async deleteUser(userId: string) { 346 | return await deleteUser(this.env, userId) 347 | } 348 | 349 | /** 350 | * List identities for a user in WorkOS. 351 | * @param userId {string} The ID of the user to list identities for (format: "user_..."). 352 | * @return {Promise<any>} List of identities for the user. 353 | */ 354 | async listIdentities(userId: string) { 355 | return await listIdentities(this.env, userId) 356 | } 357 | 358 | /** 359 | * Get an organization membership from WorkOS by ID. 360 | * @param membershipId {string} The ID of the organization membership to retrieve (format: "om_..."). 361 | * @return {Promise<any>} The organization membership details with the following properties: 362 | * - id {string} - The membership's unique identifier 363 | * - organizationId {string} - The ID of the organization 364 | * - userId {string} - The ID of the user 365 | * - status {string} - The status of the membership (active, inactive, or pending) 366 | * - role {object} - The role assigned to the user in the organization 367 | * - createdAt {string} - ISO timestamp of creation 368 | * - updatedAt {string} - ISO timestamp of last update 369 | */ 370 | async getOrganizationMembership(membershipId: string) { 371 | return await getOrganizationMembership(this.env, membershipId) 372 | } 373 | 374 | /** 375 | * List organization memberships from the WorkOS API. 376 | * @param organizationId {string} Optional organization ID to filter memberships by. 377 | * @param userId {string} Optional user ID to filter memberships by. 378 | * @param statuses {string} Optional JSON string array of statuses to filter by. Format: ["active", "inactive", "pending"] 379 | * @param limit {number} Optional limit on number of memberships to return (1-100, default 10). 380 | * @param before {string} Optional cursor for pagination (getting previous results). 381 | * @param after {string} Optional cursor for pagination (getting next results). 382 | * @return {Promise<any>} List of organization memberships matching the criteria. 383 | */ 384 | async listOrganizationMemberships( 385 | organizationId?: string, 386 | userId?: string, 387 | statuses?: string, 388 | limit?: number, 389 | before?: string, 390 | after?: string 391 | ) { 392 | // Parse the JSON string to get the array of statuses if provided 393 | const parsedStatuses = statuses 394 | ? (JSON.parse(statuses) as string[]) 395 | : undefined 396 | 397 | return await listOrganizationMemberships( 398 | this.env, 399 | organizationId, 400 | userId, 401 | parsedStatuses, 402 | limit, 403 | before, 404 | after 405 | ) 406 | } 407 | 408 | /** 409 | * Create a new organization membership in WorkOS. 410 | * @param payload {string} JSON string with membership details. Format: 411 | * { 412 | * "organizationId": "org_123", // Required: The ID of the organization 413 | * "userId": "user_123", // Required: The ID of the user 414 | * "roleSlug": "admin" // Optional: The slug of the role to assign to the user 415 | * } 416 | * @return {Promise<any>} The created organization membership. 417 | */ 418 | async createOrganizationMembership(payload: string) { 419 | // Parse the JSON string 420 | const parsedPayload = JSON.parse( 421 | payload 422 | ) as CreateOrganizationMembershipOptions 423 | 424 | return await createOrganizationMembership(this.env, parsedPayload) 425 | } 426 | 427 | /** 428 | * Update an organization membership in WorkOS. 429 | * @param membershipId {string} The ID of the organization membership to update (format: "om_..."). 430 | * @param options {string} JSON string with update options. Format: 431 | * { 432 | * "roleSlug": "admin" // Optional: The new role slug to assign to the user 433 | * } 434 | * @return {Promise<any>} The updated organization membership. 435 | */ 436 | async updateOrganizationMembership(membershipId: string, options: string) { 437 | // Parse the JSON string 438 | const parsedOptions = JSON.parse( 439 | options 440 | ) as UpdateOrganizationMembershipOptions 441 | 442 | return await updateOrganizationMembership( 443 | this.env, 444 | membershipId, 445 | parsedOptions 446 | ) 447 | } 448 | 449 | /** 450 | * Delete an organization membership from WorkOS. 451 | * @param membershipId {string} The ID of the organization membership to delete (format: "om_..."). 452 | * @return {Promise<any>} Confirmation of deletion with success status and the deleted membership ID. 453 | */ 454 | async deleteOrganizationMembership(membershipId: string) { 455 | return await deleteOrganizationMembership(this.env, membershipId) 456 | } 457 | 458 | /** 459 | * Deactivate an organization membership in WorkOS. 460 | * @param membershipId {string} The ID of the organization membership to deactivate (format: "om_..."). 461 | * @return {Promise<any>} The deactivated organization membership with status set to "inactive". 462 | */ 463 | async deactivateOrganizationMembership(membershipId: string) { 464 | return await deactivateOrganizationMembership(this.env, membershipId) 465 | } 466 | 467 | /** 468 | * Reactivate an organization membership in WorkOS. 469 | * @param membershipId {string} The ID of the organization membership to reactivate (format: "om_..."). 470 | * @return {Promise<any>} The reactivated organization membership with status set to "active". 471 | */ 472 | async reactivateOrganizationMembership(membershipId: string) { 473 | return await reactivateOrganizationMembership(this.env, membershipId) 474 | } 475 | } 476 | ``` -------------------------------------------------------------------------------- /docs.md: -------------------------------------------------------------------------------- ```markdown 1 | Title: API Reference – WorkOS Docs 2 | 3 | Events 4 | ------ 5 | 6 | [](https://workos.com/docs/reference/events) 7 | 8 | Events represent activity that has occurred within WorkOS or within third-party identity and directory providers. They are used to keep your app in sync with WorkOS data. For more details on consuming events in your app, check out the [data syncing](https://workos.com/docs/events/data-syncing) guide. 9 | 10 | Refer to the [Events](https://workos.com/docs/events) page for a full list of events that WorkOS emits. 11 | 12 | List events 13 | ----------- 14 | 15 | [](https://workos.com/docs/reference/events/list) 16 | 17 | Get a list of all of events up to 30 days old. 18 | 19 | #### `Parameters` 20 | 21 | #### `Returns ``object` 22 | 23 | Organization 24 | ------------ 25 | 26 | [](https://workos.com/docs/reference/organization) 27 | 28 | An Organization is a top-level resource in WorkOS. Each Connection, Directory, and Audit Trail Event belongs to an Organization. An Organization will usually represent one of your customers. 29 | 30 | ### `organization` 31 | 32 | Get an Organization 33 | ------------------- 34 | 35 | [](https://workos.com/docs/reference/organization/get) 36 | 37 | Get the details of an existing organization. 38 | 39 | #### `Parameters` 40 | 41 | #### `Returns` 42 | 43 | List Organizations 44 | ------------------ 45 | 46 | [](https://workos.com/docs/reference/organization/list) 47 | 48 | Get a list of all of your existing organizations matching the criteria specified. 49 | 50 | #### `Parameters` 51 | 52 | #### `Returns ``object` 53 | 54 | Create an Organization 55 | ---------------------- 56 | 57 | [](https://workos.com/docs/reference/organization/create) 58 | 59 | Creates a new organization in the current environment. 60 | 61 | You can include one or more domains to associate with the organization, but you should [verify the ownership](https://workos.com/docs/user-management/domain-verification) of every domain before setting its state to `verified`. 62 | 63 | #### `Parameters` 64 | 65 | #### `Returns` 66 | 67 | Update an Organization 68 | ---------------------- 69 | 70 | [](https://workos.com/docs/reference/organization/update) 71 | 72 | Updates an organization in the current environment. 73 | 74 | You can include one or more domains to associate with the organization, but you should [verify the ownership](https://workos.com/docs/user-management/domain-verification) of every domain before setting its state to `verified`. 75 | 76 | #### `Parameters` 77 | 78 | #### `Returns` 79 | 80 | Delete an Organization 81 | ---------------------- 82 | 83 | [](https://workos.com/docs/reference/organization/delete) 84 | 85 | Permanently deletes an organization in the current environment. It cannot be undone. 86 | 87 | #### `Parameters` 88 | 89 | Organization Domain 90 | ------------------- 91 | 92 | [](https://workos.com/docs/reference/organization-domain) 93 | 94 | An Organization Domain (also known as a User Email Domain) represents an [Organization](https://workos.com/docs/reference/organization)’s domain. 95 | 96 | These domains restrict which email addresses are able to sign in through SAML Connections when [allow profiles outside organization](https://workos.com/docs/reference/organization) is `false`. This is the default behavior for Organizations. See [SSO frequently asked questions](https://workos.com/docs/sso/launch-checklist/frequently-asked-questions) for more details on this behavior. 97 | 98 | Organization domains can be verified manually (through the API or the Dashboard), or through [a self-serve flow](https://workos.com/docs/domain-verification) through the Admin Portal. The organization that defines this domain policy exerts authentication policy control over that domain across your application. For this reason, it is important to verify ownership of manually added domains. Additionally, WorkOS does not allow addition of common consumer domains, like `gmail.com`. 99 | 100 | Example Organization Domain 101 | 102 | ### `organization_domain` 103 | 104 | List roles for an organization 105 | ------------------------------ 106 | 107 | [](https://workos.com/docs/reference/roles/list-for-organization) 108 | 109 | Get a list of all roles for the provided organization in priority order. Includes all environment and organization roles. 110 | 111 | `GET` 112 | 113 | ### `/organizations/:organization_id/roles` 114 | 115 | #### `Returns ``object` 116 | 117 | User Management 118 | --------------- 119 | 120 | [](https://workos.com/docs/reference/user-management) 121 | 122 | A set of user authentication and organization security features designed to provide a fast, scalable integration while handling all of the user management complexity that comes with advanced business and customer needs. 123 | 124 | To automatically respond to User Management activities, like authentication and changes related to the users, use the corresponding [events](https://workos.com/docs/events). 125 | 126 | User 127 | ---- 128 | 129 | [](https://workos.com/docs/reference/user-management/user) 130 | 131 | Represents a user identity in your application. A user can sign up in your application directly with a method like password, or they can be [JIT-provisioned](https://workos.com/docs/user-management/jit-provisioning) through an organization’s SSO connection. 132 | 133 | Users may belong to [organizations](https://workos.com/docs/reference/organization) as members. 134 | 135 | See the [events reference](https://workos.com/docs/events/user) documentation for the user events. 136 | 137 | ### `user` 138 | 139 | Get a user 140 | ---------- 141 | 142 | [](https://workos.com/docs/reference/user-management/user/get) 143 | 144 | Get the details of an existing user. 145 | 146 | `GET` 147 | 148 | ### `/user_management/users/:id` 149 | 150 | #### `Parameters` 151 | 152 | #### `Returns` 153 | 154 | List users 155 | ---------- 156 | 157 | [](https://workos.com/docs/reference/user-management/user/list) 158 | 159 | Get a list of all of your existing users matching the criteria specified. 160 | 161 | `GET` 162 | 163 | ### `/user_management/users` 164 | 165 | #### `Parameters` 166 | 167 | #### `Returns ``object` 168 | 169 | Create a user 170 | ------------- 171 | 172 | [](https://workos.com/docs/reference/user-management/user/create) 173 | 174 | Create a new user in the current environment. 175 | 176 | `POST` 177 | 178 | ### `/user_management/users` 179 | 180 | #### `Parameters` 181 | 182 | #### `Returns` 183 | 184 | Update a user 185 | ------------- 186 | 187 | [](https://workos.com/docs/reference/user-management/user/update) 188 | 189 | Updates properties of a user. The omitted properties will be left unchanged. 190 | 191 | `PUT` 192 | 193 | ### `/user_management/users/:id` 194 | 195 | #### `Parameters` 196 | 197 | #### `Returns` 198 | 199 | Delete a user 200 | ------------- 201 | 202 | [](https://workos.com/docs/reference/user-management/user/delete) 203 | 204 | Permanently deletes a user in the current environment. It cannot be undone. 205 | 206 | `DELETE` 207 | 208 | ### `/user_management/users/:id` 209 | 210 | #### `Parameters` 211 | 212 | Identities 213 | ---------- 214 | 215 | [](https://workos.com/docs/reference/user-management/identity) 216 | 217 | Represents [User](https://workos.com/docs/reference/user-management/user) identities obtained from external identity providers. 218 | 219 | When a user authenticates using an external provider like [Google OAuth](https://workos.com/docs/integrations/google-oauth), information from that provider will be made available as one of the user’s Identities. You can read more about the process in our [identity linking guide](https://workos.com/docs/user-management/identity-linking). 220 | 221 | Applications should check the `type` before making assumptions about the shape of the identity. Currently only `OAuth` identities are supported, but more types may be added in the future. 222 | 223 | ### `identity` 224 | 225 | Get user identities 226 | ------------------- 227 | 228 | [](https://workos.com/docs/reference/user-management/identity/list) 229 | 230 | Get a list of identities associated with the user. A user can have multiple associated identities after going through [identity linking](https://workos.com/docs/user-management/identity-linking). Currently only OAuth identities are supported. More provider types may be added in the future. 231 | 232 | `GET` 233 | 234 | ### `/user_management/users/:id/identities` 235 | 236 | #### `Parameters` 237 | 238 | #### `Returns` 239 | 240 | Authentication 241 | -------------- 242 | 243 | [](https://workos.com/docs/reference/user-management/authentication) 244 | 245 | Authenticate a user with a specified authentication method. 246 | 247 | Get an authorization URL 248 | ------------------------ 249 | 250 | [](https://workos.com/docs/reference/user-management/authentication/get-authorization-url) 251 | 252 | Generates an OAuth 2.0 authorization URL to authenticate a user with AuthKit or SSO. 253 | 254 | `GET` 255 | 256 | ### `/user_management/authorize` 257 | 258 | #### `Returns` 259 | 260 | If you are using AuthKit, set the provider parameter to `"authkit"`, which will generate an authorization URL for your AuthKit domain. AuthKit will take care of detecting the user’s authentication method, such as identifying whether they use Email + Password or Single Sign-On,and direct them to the corresponding login flow. 261 | 262 | Otherwise, to generate an authorization URL for a WorkOS SSO connection, you’ll have to specify the user’s connection, organization, or OAuth provider as a parameter. These connection selectors are mutually exclusive, and exactly one must be provided. The generated URL automatically directs the user to their identity provider. Once the user authenticates with their identity provider, WorkOS then issues a redirect to your redirect URI to complete the sign-in flow. 263 | 264 | ### Redirect URI 265 | 266 | In the [OAuth 2.0](https://workos.com/docs/glossary/oauth-2-0) protocol, a redirect URI is the location that the user is redirected to once they have successfully authenticated with their identity provider. 267 | 268 | When redirecting the user, WorkOS will generate an authorization code and pass it to your redirect URI as a `code` query parameter, your app will use this code to [authenticate the user](https://workos.com/docs/reference/user-management/authentication/code). Additionally, WorkOS can pass a `state` parameter back to your application that you may use to encode arbitrary information to restore your application state between the redirects. 269 | 270 | Redirect URI with query parameters 271 | 272 | You can use `state` to encode parameters like originating URL and query parameters. This is useful in a flow where unauthenticated users are automatically redirected to a login page. After successful sign in, users will be routed to your redirect URI callback route. From there you can extract the originating URL from `state` and redirect the user to their intended destination. 273 | 274 | You’ll need to configure the allowed redirect URIs for your application via the [Redirects](https://dashboard.workos.com/redirects) page in the dashboard. Without a valid redirect URI, your users will be unable to sign in. Make sure that the redirect URI you use as a parameter to get the authorization URL matches one of the redirect URIs you have configured in the dashboard. 275 | 276 | Redirect URIs follow stricter requirements in production environments: 277 | 278 | * `HTTPS` protocol is required in production environments 279 | 280 | * `HTTP` and `localhost` are allowed in staging environments 281 | 282 | * Wildcard characters are not allowed in production environments 283 | 284 | Organization membership 285 | ----------------------- 286 | 287 | [](https://workos.com/docs/reference/user-management/organization-membership) 288 | 289 | An organization membership is a top-level resource that represents a [user](https://workos.com/docs/reference/user-management/user)’s relationship with an [organization](https://workos.com/docs/reference/organization). A user may be a member of zero, one, or many organizations. 290 | 291 | See the [events reference](https://workos.com/docs/events/organization-membership) documentation for the organization membership events. 292 | 293 | Example organization membership 294 | 295 | ### `organization_membership` 296 | 297 | Get an organization membership 298 | ------------------------------ 299 | 300 | [](https://workos.com/docs/reference/user-management/organization-membership/get) 301 | 302 | Get the details of an existing organization membership. 303 | 304 | `GET` 305 | 306 | ### `/user_management/organization_memberships/:id` 307 | 308 | #### `Parameters` 309 | 310 | #### `Returns` 311 | 312 | List organization memberships 313 | ----------------------------- 314 | 315 | [](https://workos.com/docs/reference/user-management/organization-membership/list) 316 | 317 | Get a list of all organization memberships matching the criteria specified. By default only active memberships are returned. Use the `statuses` parameter to filter by other statuses. 318 | 319 | `GET` 320 | 321 | ### `/user_management/organization_memberships` 322 | 323 | #### `Parameters` 324 | 325 | #### `Returns ``object` 326 | 327 | Create an organization membership 328 | --------------------------------- 329 | 330 | [](https://workos.com/docs/reference/user-management/organization-membership/create) 331 | 332 | Creates a new `active` organization membership for the given organization and user. 333 | 334 | Calling this API with an organization and user that match an `inactive` organization membership will activate the membership with the specified role. 335 | 336 | `POST` 337 | 338 | ### `/user_management/organization_memberships` 339 | 340 | #### `Parameters` 341 | 342 | #### `Returns` 343 | 344 | Update an organization membership 345 | --------------------------------- 346 | 347 | [](https://workos.com/docs/reference/user-management/organization-membership/update) 348 | 349 | Update the details of an existing organization membership. 350 | 351 | `PUT` 352 | 353 | ### `/user_management/organization_memberships/:id` 354 | 355 | #### `Parameters` 356 | 357 | #### `Returns` 358 | 359 | Delete an organization membership 360 | --------------------------------- 361 | 362 | [](https://workos.com/docs/reference/user-management/organization-membership/delete) 363 | 364 | Permanently deletes an existing organization membership. It cannot be undone. 365 | 366 | `DELETE` 367 | 368 | ### `/user_management/organization_memberships/:id` 369 | 370 | #### `Parameters` 371 | 372 | Deactivate an organization membership 373 | ------------------------------------- 374 | 375 | [](https://workos.com/docs/reference/user-management/organization-membership/deactivate) 376 | 377 | Deactivates an `active` organization membership. Emits an [organization\_membership.updated](https://workos.com/docs/events/organization-membership) event upon successful deactivation. 378 | 379 | * Deactivating an `inactive` membership is a no-op and does not emit an event. 380 | 381 | * Deactivating a `pending` membership returns an error. This membership should be [deleted](https://workos.com/docs/reference/user-management/organization-membership/delete) instead. 382 | 383 | See the [membership management documentation](https://workos.com/docs/user-management/users-organizations/organizations/membership-management) for additional details. 384 | 385 | `PUT` 386 | 387 | ### `/user_management/organization_memberships/:id/deactivate` 388 | 389 | #### `Parameters` 390 | 391 | #### `Returns` 392 | 393 | Reactivate an organization membership 394 | ------------------------------------- 395 | 396 | [](https://workos.com/docs/reference/user-management/organization-membership/reactivate) 397 | 398 | Reactivates an `inactive` organization membership, retaining the pre-existing role. Emits an [organization\_membership.updated](https://workos.com/docs/events/organization-membership) event upon successful reactivation. 399 | 400 | * Reactivating an `active` membership is a no-op and does not emit an event. 401 | 402 | * Reactivating a `pending` membership returns an error. The user needs to [accept the invitation](https://workos.com/docs/user-management/invitations) instead. 403 | 404 | See the [membership management documentation](https://workos.com/docs/user-management/users-organizations/organizations/membership-management) for additional details. 405 | 406 | `PUT` 407 | 408 | ### `/user_management/organization_memberships/:id/reactivate` 409 | 410 | #### `Parameters` 411 | 412 | #### `Returns` 413 | 414 | Invitation 415 | ---------- 416 | 417 | [](https://workos.com/docs/reference/user-management/invitation) 418 | 419 | An email invitation allows the recipient to sign up for your app and join a specific [organization](https://workos.com/docs/reference/organization). When an invitation is accepted, a [user](https://workos.com/docs/reference/user-management/user) and a corresponding [organization membership](https://workos.com/docs/reference/user-management/organization-membership) are created. 420 | 421 | Users may be invited to your app without joining an organization, or they may be invited to join an organization if they already have an account. Invitations may be also issued on behalf of another user. In this case, the invitation email will mention the name of the user who invited the recipient. 422 | 423 | Get an invitation 424 | ----------------- 425 | 426 | [](https://workos.com/docs/reference/user-management/invitation/get) 427 | 428 | Get the details of an existing invitation. 429 | 430 | `GET` 431 | 432 | ### `/user_management/invitations/:id` 433 | 434 | #### `Parameters` 435 | 436 | #### `Returns` 437 | 438 | Find an invitation by token 439 | --------------------------- 440 | 441 | [](https://workos.com/docs/reference/user-management/invitation/find-by-token) 442 | 443 | Retrieve an existing invitation using the token. 444 | 445 | `GET` 446 | 447 | ### `/user_management/invitations/by_token/:token` 448 | 449 | #### `Parameters` 450 | 451 | #### `Returns` 452 | 453 | List invitations 454 | ---------------- 455 | 456 | [](https://workos.com/docs/reference/user-management/invitation/list) 457 | 458 | Get a list of all of invitations matching the criteria specified. 459 | 460 | `GET` 461 | 462 | ### `/user_management/invitations` 463 | 464 | #### `Parameters` 465 | 466 | #### `Returns ``object` 467 | 468 | Send an invitation 469 | ------------------ 470 | 471 | [](https://workos.com/docs/reference/user-management/invitation/send) 472 | 473 | Sends an invitation email to the recipient. 474 | 475 | `POST`Sends email 476 | 477 | ### `/user_management/invitations` 478 | 479 | #### `Parameters` 480 | 481 | #### `Returns` 482 | 483 | Accept an invitation 484 | -------------------- 485 | 486 | [](https://workos.com/docs/reference/user-management/invitation/accept) 487 | 488 | Accepts an invitation and, if linked to an organization, activates the user’s membership in that organization. 489 | 490 | In most cases, use existing authentication methods like [`authenticateWithCode`](https://workos.com/docs/reference/user-management/authentication/code), which also accept an invitation token. These methods offer the same functionality (invitation acceptance and membership activation) while also signing the user in. 491 | 492 | This method is useful for apps requiring a highly customized invitation flow, as it focuses solely on handling invitations without authentication. It’s also helpful when users can be invited to multiple organizations and need a way to accept invitations after signing in. 493 | 494 | Your application should verify that the invitation is intended for the user accepting it. For example, by fetching the invitation using the [find-by-token endpoint](https://workos.com/docs/reference/user-management/invitation/find-by-token) and ensuring the email matches the email address of the accepting user. 495 | 496 | `POST` 497 | 498 | ### `/user_management/invitations/:id/accept` 499 | 500 | #### `Parameters` 501 | 502 | #### `Returns` 503 | 504 | Revoke an invitation 505 | -------------------- 506 | 507 | [](https://workos.com/docs/reference/user-management/invitation/revoke) 508 | 509 | Revokes an existing invitation. 510 | 511 | `POST` 512 | 513 | ### `/user_management/invitations/:id/revoke` 514 | 515 | #### `Parameters` 516 | 517 | #### `Returns` 518 | 519 | Logout 520 | ------ 521 | 522 | [](https://workos.com/docs/reference/user-management/logout) 523 | 524 | End a user’s session. The user’s browser should be redirected to this URL. 525 | 526 | Get logout URL 527 | -------------- 528 | 529 | [](https://workos.com/docs/reference/user-management/logout/get-logout-url) 530 | 531 | `GET` 532 | 533 | ### `/user_management/sessions/logout` 534 | 535 | #### `Parameters` 536 | 537 | #### `Returns` 538 | 539 | Get logout URL from session cookie 540 | ---------------------------------- 541 | 542 | [](https://workos.com/docs/reference/user-management/logout/get-logout-url-from-session-cookie) 543 | 544 | Generates the logout URL by extracting the session ID from the session cookie. Use this over `getLogoutUrl` if you don’t have a saved reference to the session ID and you’d like the SDK to handle extracting the session ID from the cookie for you. 545 | 546 | ### `userManagement.getLogoutUrlFromSessionCookie()` 547 | 548 | #### `Parameters ``object` 549 | 550 | #### `Returns` 551 | 552 | Single Sign-On 553 | -------------- 554 | 555 | [](https://workos.com/docs/reference/sso) 556 | 557 | The Single Sign-On API has been modeled to meet the [OAuth 2.0](https://workos.com/docs/glossary/oauth-2-0) framework specification. As a result, authentication flows constructed using the Single Sign-On API replicate the OAuth 2.0 protocol flow. 558 | 559 | To automatically respond to changes in your SSO connections, use the [Connection events](https://workos.com/docs/events/connection). 560 | 561 | Get an authorization URL 562 | ------------------------ 563 | 564 | [](https://workos.com/docs/reference/sso/get-authorization-url) 565 | 566 | Generates an OAuth 2.0 authorization URL to authenticate a user with SSO. 567 | 568 | #### `Returns` 569 | 570 | You’ll have to specify the user’s connection, organization, or OAuth provider as a parameter. These connection selectors are mutually exclusive, and exactly one must be provided. The generated URL automatically directs the user to their identity provider. Once the user authenticates with their identity provider, WorkOS then issues a redirect to your redirect URI to complete the sign-in flow. 571 | 572 | ### Redirect URI 573 | 574 | In the [OAuth 2.0](https://workos.com/docs/glossary/oauth-2-0) protocol, a redirect URI is the location that the user is redirected to once they have successfully authenticated with their identity provider. 575 | 576 | When redirecting the user, WorkOS will generate an authorization code and pass it to your redirect URI as a `code` query parameter, your app will use this code to [get the user’s profile](https://workos.com/docs/reference/sso/profile/get-profile-and-token). Additionally, WorkOS can pass a `state` parameter back to your application that you may use to encode arbitrary information to restore your application state between the redirects. 577 | 578 | Redirect URI with query parameters 579 | 580 | You’ll need to configure the allowed redirect URIs for your application via the [Redirects](https://dashboard.workos.com/redirects) page in the dashboard. Without a valid redirect URI, your users will be unable to sign in. Make sure that the redirect URI you use as a parameter to get the authorization URL matches one of the redirect URIs you have configured in the dashboard. 581 | 582 | Redirect URIs follow stricter requirements in production environments: 583 | 584 | * `HTTPS` protocol is required in production environments 585 | 586 | * `HTTP` and `localhost` are allowed in staging environments 587 | 588 | * Wildcard characters are not allowed in production environments 589 | 590 | ### Error codes 591 | 592 | If there is an issue generating an authorization URL, the API will return the original redirect URI with `error` and `error_description` query parameters. If provided, the `state` value will also be included. 593 | 594 | Redirect URI with an error code 595 | 596 | Possible error codes and the corresponding descriptions are listed below. 597 | 598 | Profile 599 | ------- 600 | 601 | [](https://workos.com/docs/reference/sso/profile) 602 | 603 | A Profile is an object that represents an authenticated user. The Profile object contains information relevant to a user in the form of normalized attributes. 604 | 605 | After receiving the Profile for an authenticated user, use the Profile object attributes to persist relevant data to your application’s user model for the specific, authenticated user. 606 | 607 | No Profile attributes can be returned other than the normalized attributes listed below. 608 | 609 | ### `profile` 610 | 611 | Get a Profile and Token 612 | ----------------------- 613 | 614 | [](https://workos.com/docs/reference/sso/profile/get-profile-and-token) 615 | 616 | Get an access token along with the user [Profile](https://workos.com/docs/reference/sso/profile) using the code passed to your [Redirect URI](https://workos.com/docs/reference/sso/get-authorization-url/redirect-uri). 617 | 618 | #### `Parameters` 619 | 620 | #### `Returns ``object` 621 | 622 | Get a User Profile 623 | ------------------ 624 | 625 | [](https://workos.com/docs/reference/sso/profile/get-user-profile) 626 | 627 | Exchange an access token for a user’s [Profile](https://workos.com/docs/reference/sso/profile). Because this profile is returned in the [Get a Profile and Token endpoint](https://workos.com/docs/reference/sso/profile/get-profile-and-token) your application usually does not need to call this endpoint. It is available for any authentication flows that require an additional endpoint to retrieve a user’s profile. 628 | 629 | #### `Parameters` 630 | 631 | #### `Returns` 632 | 633 | Connection 634 | ---------- 635 | 636 | [](https://workos.com/docs/reference/sso/connection) 637 | 638 | A connection represents the relationship between WorkOS and any collection of application users. This collection of application users may include personal or enterprise identity providers. As a layer of abstraction, a WorkOS connection rests between an application and its users, separating an application from the implementation details required by specific standards like [OAuth 2.0](https://workos.com/docs/glossary/oauth-2-0) and [SAML](https://workos.com/docs/glossary/saml). 639 | 640 | See the [events reference](https://workos.com/docs/events/connection) documentation for the connection events. 641 | 642 | ### `connection` 643 | 644 | Get a Connection 645 | ---------------- 646 | 647 | [](https://workos.com/docs/reference/sso/connection/get) 648 | 649 | Get the details of an existing connection. 650 | 651 | #### `Parameters` 652 | 653 | #### `Returns` 654 | 655 | List Connections 656 | ---------------- 657 | 658 | [](https://workos.com/docs/reference/sso/connection/list) 659 | 660 | Get a list of all of your existing connections matching the criteria specified. 661 | 662 | #### `Parameters` 663 | 664 | #### `Returns ``object` 665 | 666 | Delete a Connection 667 | ------------------- 668 | 669 | [](https://workos.com/docs/reference/sso/connection/delete) 670 | 671 | Permanently deletes an existing connection. It cannot be undone. 672 | 673 | #### `Parameters` 674 | 675 | Directory Sync 676 | -------------- 677 | 678 | [](https://workos.com/docs/reference/directory-sync) 679 | 680 | Directory Sync allows you to connect with directory providers to inform your application of any changes in their users, groups, or access rules. 681 | 682 | Using Directory Sync, one integration grants your application the ability to support multiple directory providers. Get real-time updates of any changes to the organization’s access rules, groups, and users by integrating webhooks into your application. 683 | 684 | To automatically respond to changes in the connected directories and their users and groups, use the [Directory Sync events](https://workos.com/docs/events/directory-sync). 685 | 686 | Directory 687 | --------- 688 | 689 | [](https://workos.com/docs/reference/directory-sync/directory) 690 | 691 | A directory stores information about an organization’s employee management system. 692 | 693 | Synchronizing with a directory enables you to receive changes to an organization’s [user](https://workos.com/docs/reference/directory-sync/directory-user) and [group](https://workos.com/docs/reference/directory-sync/directory-group) structure. 694 | 695 | Directory providers vary in implementation details and may require different sets of fields for integration, such as API keys, subdomains, endpoints, usernames, etc. Where available, the WorkOS API will provide these fields when fetching directory records. 696 | 697 | ### `directory` 698 | 699 | Get a Directory 700 | --------------- 701 | 702 | [](https://workos.com/docs/reference/directory-sync/directory/get) 703 | 704 | Get the details of an existing directory. 705 | 706 | #### `Parameters` 707 | 708 | #### `Returns` 709 | 710 | List Directories 711 | ---------------- 712 | 713 | [](https://workos.com/docs/reference/directory-sync/directory/list) 714 | 715 | Get a list of all of your existing directories matching the criteria specified. 716 | 717 | #### `Parameters` 718 | 719 | #### `Returns ``object` 720 | 721 | Delete a Directory 722 | ------------------ 723 | 724 | [](https://workos.com/docs/reference/directory-sync/directory/delete) 725 | 726 | Permanently deletes an existing directory. It cannot be undone. 727 | 728 | #### `Parameters` 729 | 730 | Directory User 731 | -------------- 732 | 733 | [](https://workos.com/docs/reference/directory-sync/directory-user) 734 | 735 | A Directory User represents an active organization user. 736 | 737 | Developers can receive [Webhooks](https://workos.com/docs/events/directory-sync) as employees are added, updated or removed, allowing for provisioning and de-provisioning Users within an application. 738 | 739 | ### `directory_user` 740 | 741 | Get a Directory User 742 | -------------------- 743 | 744 | [](https://workos.com/docs/reference/directory-sync/directory-user/get) 745 | 746 | Get the details of an existing Directory User. 747 | 748 | #### `Parameters` 749 | 750 | #### `Returns` 751 | 752 | List Directory Users 753 | -------------------- 754 | 755 | [](https://workos.com/docs/reference/directory-sync/directory-user/list) 756 | 757 | Get a list of all of existing Directory Users matching the criteria specified. 758 | 759 | #### `Parameters` 760 | 761 | #### `Returns ``object` 762 | 763 | Directory Group 764 | --------------- 765 | 766 | [](https://workos.com/docs/reference/directory-sync/directory-group) 767 | 768 | A directory group represents an organizational unit of users in a directory provider. 769 | 770 | ### `directory_group` 771 | 772 | Get a Directory Group 773 | --------------------- 774 | 775 | [](https://workos.com/docs/reference/directory-sync/directory-group/get) 776 | 777 | Get the details of an existing Directory Group. 778 | 779 | #### `Parameters` 780 | 781 | #### `Returns` 782 | 783 | List Directory Groups 784 | --------------------- 785 | 786 | [](https://workos.com/docs/reference/directory-sync/directory-group/list) 787 | 788 | Get a list of all of existing directory groups matching the criteria specified. 789 | 790 | #### `Parameters` 791 | 792 | #### `Returns ``object` 793 | 794 | Admin Portal 795 | ------------ 796 | 797 | [](https://workos.com/docs/reference/admin-portal) 798 | 799 | The Admin Portal is a standalone application where your users can configure and manage WorkOS resources such as [Connections](https://workos.com/docs/reference/sso/connection) and [Directories](https://workos.com/docs/reference/directory-sync/directory) that are scoped to their [Organization](https://workos.com/docs/reference/organization). 800 | 801 | Portal Link 802 | ----------- 803 | 804 | [](https://workos.com/docs/reference/admin-portal/portal-link) 805 | 806 | A Portal Link is a temporary endpoint to initiate an Admin Portal session. It expires five minutes after issuance. 807 | 808 | Generate a Portal Link 809 | ---------------------- 810 | 811 | [](https://workos.com/docs/reference/admin-portal/portal-link/generate) 812 | 813 | Generate a Portal Link scoped to an Organization. 814 | 815 | `POST` 816 | 817 | ### `/portal/generate_link` 818 | 819 | #### `Parameters` 820 | 821 | #### `Returns ``object` 822 | 823 | Provider Icons 824 | -------------- 825 | 826 | [](https://workos.com/docs/reference/admin-portal/provider-icons) 827 | 828 | Icons for third-party providers are available through the WorkOS CDN. These icons cover identity providers, Directory Sync, and domain verification services used within the Admin Portal. 829 | 830 | ### List Provider Icons 831 | 832 | Get a list of all of existing provider icons. 833 | 834 | ResourcesThe icons are also available as a Figma community file. 835 | 836 | [Open in Figma](https://www.figma.com/community/file/1408148024751538607/provider-icons) 837 | 838 | ### Get a Provider Icon 839 | 840 | To use an icon in your project, you can reference the CDN link directly. You can alternate between light and dark mode icons by changing the path in the URL or using CSS media queries. 841 | 842 | You can change the icons to grayscale by adding the `filter` CSS property. 843 | 844 | Audit Logs 845 | ---------- 846 | 847 | [](https://workos.com/docs/reference/audit-logs) 848 | 849 | Audit Logs are a collection of events that contain information relevant to notable actions taken by users in your application. Every event in the collection contains details regarding what kind of action was taken (`action`), who performed the action (`actor`), what resources were affected by the action (`targets`), and additional details of when and where the action took place. 850 | 851 | Create Event 852 | ------------ 853 | 854 | [](https://workos.com/docs/reference/audit-logs/create-event) 855 | 856 | Emits an Audit Log Event. 857 | 858 | #### `Parameters` 859 | 860 | Audit Log Schema 861 | ---------------- 862 | 863 | [](https://workos.com/docs/reference/audit-logs/audit-log-schema) 864 | 865 | An object representing an Audit Log Schema. 866 | 867 | ### `audit_log_schema` 868 | 869 | Create Schema 870 | ------------- 871 | 872 | [](https://workos.com/docs/reference/audit-logs/create-schema) 873 | 874 | Creates a new Audit Log schema used to validate the payload of incoming Audit Log Events. If the `action` does not exist, it will also be created. 875 | 876 | `POST` 877 | 878 | ### `/audit_logs/actions/:name/schemas` 879 | 880 | #### `Parameters` 881 | 882 | #### `Returns` 883 | 884 | List Schemas 885 | ------------ 886 | 887 | [](https://workos.com/docs/reference/audit-logs/list-schemas) 888 | 889 | Get a list of all schemas for the Audit Logs action identified by `:name`. 890 | 891 | `GET` 892 | 893 | ### `/audit_logs/actions/:name/schemas` 894 | 895 | #### `Parameters` 896 | 897 | #### `Returns ``object` 898 | 899 | List Actions 900 | ------------ 901 | 902 | [](https://workos.com/docs/reference/audit-logs/list-actions) 903 | 904 | Get a list of all Audit Log actions in the current environment. 905 | 906 | #### `Parameters` 907 | 908 | #### `Returns ``object` 909 | 910 | Audit Log Export 911 | ---------------- 912 | 913 | [](https://workos.com/docs/reference/audit-logs/audit-log-export) 914 | 915 | An object representing an Audit Log Export. 916 | 917 | ### `audit_log_export` 918 | 919 | Create Export 920 | ------------- 921 | 922 | [](https://workos.com/docs/reference/audit-logs/create-export) 923 | 924 | Create an Audit Log Export. 925 | 926 | #### `Parameters` 927 | 928 | #### `Returns` 929 | 930 | Get Export 931 | ---------- 932 | 933 | [](https://workos.com/docs/reference/audit-logs/get-export) 934 | 935 | Get an Audit Log Export. 936 | 937 | `GET` 938 | 939 | ### `/audit_logs/exports/:id` 940 | 941 | #### `Parameters` 942 | 943 | #### `Returns` 944 | 945 | The URL will expire after 10 minutes. If the export is needed again at a later time, refetching the export will regenerate the URL. 946 | 947 | Get Retention 948 | ------------- 949 | 950 | [](https://workos.com/docs/reference/audit-logs/get-retention) 951 | 952 | Get the configured event retention period for the given Organization. 953 | 954 | `GET` 955 | 956 | ### `/organizations/:id/audit_logs_retention` 957 | 958 | #### `Parameters` 959 | 960 | #### `Returns ``object` 961 | 962 | Set Retention 963 | ------------- 964 | 965 | [](https://workos.com/docs/reference/audit-logs/set-retention) 966 | 967 | Set the event retention period for the given Organization. 968 | 969 | `PUT` 970 | 971 | ### `/organizations/:id/audit_logs_retention` 972 | 973 | #### `Parameters` 974 | 975 | #### `Returns ``object` 976 | 977 | Organization domain 978 | ------------------- 979 | 980 | [](https://workos.com/docs/reference/domain-verification) 981 | 982 | An organization domain represents an [organization](https://workos.com/docs/reference/organization)’s domain. Domains can be verified to assert that an organization owns the configured domain which is accomplished through DNS TXT record verification. 983 | 984 | To automatically respond to changes in the organization domains, use [Domain Verification events](https://workos.com/docs/events/organization-domain). 985 | 986 | Example organization domain 987 | 988 | Get an Organization Domain 989 | -------------------------- 990 | 991 | [](https://workos.com/docs/reference/domain-verification/get) 992 | 993 | Get the details of an existing organization. 994 | 995 | `GET` 996 | 997 | ### `/organization_domains/:id` 998 | 999 | #### `Parameters` 1000 | 1001 | #### `Returns` 1002 | 1003 | Create an Organization Domain 1004 | ----------------------------- 1005 | 1006 | [](https://workos.com/docs/reference/domain-verification/create) 1007 | 1008 | Creates a new Organization Domain. 1009 | 1010 | `POST` 1011 | 1012 | ### `/organization-domains` 1013 | 1014 | #### `Parameters` 1015 | 1016 | #### `Returns` 1017 | 1018 | Verify an Organization Domain 1019 | ----------------------------- 1020 | 1021 | [](https://workos.com/docs/reference/domain-verification/verify) 1022 | 1023 | Initiates verification process for an Organization Domain. 1024 | 1025 | `POST` 1026 | 1027 | ### `/organization-domains/:id/verify` 1028 | 1029 | #### `Parameters` 1030 | 1031 | #### `Returns` 1032 | 1033 | Authentication Factor 1034 | --------------------- 1035 | 1036 | [](https://workos.com/docs/reference/mfa/authentication-factor) 1037 | 1038 | An object representing an Authentication Factor. 1039 | 1040 | Example Authentication Factor 1041 | 1042 | ### `authentication_factor` 1043 | 1044 | Authentication Challenge 1045 | ------------------------ 1046 | 1047 | [](https://workos.com/docs/reference/mfa/authentication-challenge) 1048 | 1049 | An object representing a Challenge of an Authentication Factor. 1050 | 1051 | Example Authentication Challenge 1052 | 1053 | ### `authentication_challenge` 1054 | 1055 | Enroll Factor 1056 | ------------- 1057 | 1058 | [](https://workos.com/docs/reference/mfa/enroll-factor) 1059 | 1060 | Enrolls an Authentication Factor to be used as an additional factor of authentication. The returned ID should be used to create an authentication Challenge. 1061 | 1062 | #### `Parameters` 1063 | 1064 | #### `Returns` 1065 | 1066 | Challenge Factor 1067 | ---------------- 1068 | 1069 | [](https://workos.com/docs/reference/mfa/challenge-factor) 1070 | 1071 | Creates a Challenge for an Authentication Factor. 1072 | 1073 | `POST` 1074 | 1075 | ### `/auth/factors/:id/challenge` 1076 | 1077 | #### `Parameters` 1078 | 1079 | #### `Returns` 1080 | 1081 | Verify Challenge 1082 | ---------------- 1083 | 1084 | [](https://workos.com/docs/reference/mfa/verify-challenge) 1085 | 1086 | Verify Authentication Challenge. 1087 | 1088 | `POST` 1089 | 1090 | ### `/auth/challenges/:id/verify` 1091 | 1092 | #### `Parameters` 1093 | 1094 | #### `Returns ``object` 1095 | 1096 | Get Factor 1097 | ---------- 1098 | 1099 | [](https://workos.com/docs/reference/mfa/get-factor) 1100 | 1101 | Gets an Authentication Factor. 1102 | 1103 | #### `Parameters` 1104 | 1105 | #### `Returns` 1106 | 1107 | Delete Factor 1108 | ------------- 1109 | 1110 | [](https://workos.com/docs/reference/mfa/delete-factor) 1111 | 1112 | Permanently deletes an Authentication Factor. It cannot be undone. 1113 | 1114 | #### `Parameters` 1115 | 1116 | Fine-Grained Authorization 1117 | -------------------------- 1118 | 1119 | [](https://workos.com/docs/reference/fga) 1120 | 1121 | Fine-Grained Authorization (FGA) is a set of APIs designed to help you implement scalable, centralized, fine grained authorization in your application. 1122 | 1123 | Resource Type 1124 | ------------- 1125 | 1126 | [](https://workos.com/docs/reference/fga/resource-type) 1127 | 1128 | Represents a type of resource and its possible relationships in your application. 1129 | 1130 | ### `resource_type` 1131 | 1132 | Get a resource type 1133 | ------------------- 1134 | 1135 | [](https://workos.com/docs/reference/fga/resource-type/get) 1136 | 1137 | Get the definition of an existing resource type. 1138 | 1139 | `GET` 1140 | 1141 | ### `/fga/v1/resource-types/:type` 1142 | 1143 | #### `Parameters` 1144 | 1145 | #### `Returns` 1146 | 1147 | List resource types 1148 | ------------------- 1149 | 1150 | [](https://workos.com/docs/reference/fga/resource-type/list) 1151 | 1152 | Get a list of all your existing resource types matching the criteria specified. 1153 | 1154 | `GET` 1155 | 1156 | ### `/fga/v1/resource-types` 1157 | 1158 | #### `Parameters` 1159 | 1160 | #### `Returns` 1161 | 1162 | Create a resource type 1163 | ---------------------- 1164 | 1165 | [](https://workos.com/docs/reference/fga/resource-type/create) 1166 | 1167 | Create a new resource type in the current environment. 1168 | 1169 | `POST` 1170 | 1171 | ### `/fga/v1/resource-types` 1172 | 1173 | #### `Parameters` 1174 | 1175 | #### `Returns` 1176 | 1177 | Update a resource type 1178 | ---------------------- 1179 | 1180 | [](https://workos.com/docs/reference/fga/resource-type/update) 1181 | 1182 | Update properties of a resource type. 1183 | 1184 | `PUT` 1185 | 1186 | ### `/fga/v1/resource-types` 1187 | 1188 | #### `Parameters` 1189 | 1190 | #### `Returns` 1191 | 1192 | Delete a resource type 1193 | ---------------------- 1194 | 1195 | [](https://workos.com/docs/reference/fga/resource-type/delete) 1196 | 1197 | Deletes a resource type in the current environment. 1198 | 1199 | `DELETE` 1200 | 1201 | ### `/fga/v1/resource-types/:type` 1202 | 1203 | #### `Parameters` 1204 | 1205 | Apply resource types 1206 | -------------------- 1207 | 1208 | [](https://workos.com/docs/reference/fga/resource-type/apply) 1209 | 1210 | Sets resource types in the current environment to match the provided resource types. 1211 | 1212 | This endpoint performs a batch operation which will override your entire schema for the environment. Any existing resource types not included in the request will be deleted. 1213 | 1214 | `PUT` 1215 | 1216 | ### `/fga/v1/resource-types` 1217 | 1218 | #### `Parameters` 1219 | 1220 | #### `Returns` 1221 | 1222 | Warrant 1223 | ------- 1224 | 1225 | [](https://workos.com/docs/reference/fga/warrant) 1226 | 1227 | Represents a relation between resources in your application. 1228 | 1229 | ### `warrant` 1230 | 1231 | List warrants 1232 | ------------- 1233 | 1234 | [](https://workos.com/docs/reference/fga/warrant/list) 1235 | 1236 | Get a list of all your existing warrants matching the criteria specified. 1237 | 1238 | #### `Parameters` 1239 | 1240 | #### `Returns` 1241 | 1242 | Write a warrant 1243 | --------------- 1244 | 1245 | [](https://workos.com/docs/reference/fga/warrant/write) 1246 | 1247 | Creates or deletes a warrant in the current environment. 1248 | 1249 | ### Create Warrant 1250 | 1251 | #### `Parameters` 1252 | 1253 | #### `Returns ``object` 1254 | 1255 | ### Delete Warrant 1256 | 1257 | #### `Parameters` 1258 | 1259 | #### `Returns ``object` 1260 | 1261 | Batch Write Warrants 1262 | -------------------- 1263 | 1264 | [](https://workos.com/docs/reference/fga/warrant/batch-write) 1265 | 1266 | Executes a batch of warrant writes in the current environment. 1267 | 1268 | #### `Parameters` 1269 | 1270 | #### `Returns` 1271 | 1272 | Resource 1273 | -------- 1274 | 1275 | [](https://workos.com/docs/reference/fga/resource) 1276 | 1277 | Represents a resource in your application. 1278 | 1279 | ### `resource` 1280 | 1281 | Get a resource 1282 | -------------- 1283 | 1284 | [](https://workos.com/docs/reference/fga/resource/get) 1285 | 1286 | Get an existing resource. 1287 | 1288 | `GET` 1289 | 1290 | ### `/fga/v1/resources/:resource_type/:resource_id` 1291 | 1292 | #### `Parameters` 1293 | 1294 | #### `Returns` 1295 | 1296 | List resources 1297 | -------------- 1298 | 1299 | [](https://workos.com/docs/reference/fga/resource/list) 1300 | 1301 | Get a list of all your existing resources matching the criteria specified. 1302 | 1303 | #### `Parameters` 1304 | 1305 | #### `Returns` 1306 | 1307 | Create a resource 1308 | ----------------- 1309 | 1310 | [](https://workos.com/docs/reference/fga/resource/create) 1311 | 1312 | Create a new resource in the current environment. 1313 | 1314 | #### `Parameters` 1315 | 1316 | #### `Returns` 1317 | 1318 | Update a resource 1319 | ----------------- 1320 | 1321 | [](https://workos.com/docs/reference/fga/resource/update) 1322 | 1323 | Update the meta of an existing resource in the current environment. 1324 | 1325 | `PUT` 1326 | 1327 | ### `/fga/v1/resources/:resource_type/:resource_id` 1328 | 1329 | #### `Parameters` 1330 | 1331 | #### `Returns` 1332 | 1333 | Delete a resource 1334 | ----------------- 1335 | 1336 | [](https://workos.com/docs/reference/fga/resource/delete) 1337 | 1338 | Deletes a resource in the current environment. 1339 | 1340 | `DELETE` 1341 | 1342 | ### `/fga/v1/resources/:resource_type/:resource_id` 1343 | 1344 | #### `Parameters` 1345 | 1346 | Batch write resources 1347 | --------------------- 1348 | 1349 | [](https://workos.com/docs/reference/fga/resource/batch-write) 1350 | 1351 | Create or delete up to 100 resources in one request. 1352 | 1353 | ### Batch create resources 1354 | 1355 | `POST` 1356 | 1357 | ### `/fga/v1/resources/batch` 1358 | 1359 | #### `Parameters` 1360 | 1361 | #### `Returns` 1362 | 1363 | ### Batch delete resources 1364 | 1365 | `POST` 1366 | 1367 | ### `/fga/v1/resources/batch` 1368 | 1369 | #### `Parameters` 1370 | 1371 | #### `Returns` 1372 | 1373 | Check 1374 | ----- 1375 | 1376 | [](https://workos.com/docs/reference/fga/check) 1377 | 1378 | Check if a subject has a particular relation on a resource. 1379 | 1380 | Single Check 1381 | ------------ 1382 | 1383 | #### `Parameters` 1384 | 1385 | #### `Returns ``object` 1386 | 1387 | Multiple Checks 1388 | --------------- 1389 | 1390 | #### `Parameters` 1391 | 1392 | #### `Returns ``object` 1393 | 1394 | Batch Check 1395 | ----------- 1396 | 1397 | [](https://workos.com/docs/reference/fga/batch-check) 1398 | 1399 | Executes a batch of checks and returns a list of results in a single operation. 1400 | 1401 | #### `Parameters` 1402 | 1403 | #### `Returns` 1404 | 1405 | Query 1406 | ----- 1407 | 1408 | [](https://workos.com/docs/reference/fga/query) 1409 | 1410 | Use the [Query Language](https://workos.com/docs/fga/query-language) to list the set of subjects that have access to a particular resource or to list the set of resources a particular subject has access to. 1411 | 1412 | #### `Parameters` 1413 | 1414 | #### `Returns ``object` 1415 | 1416 | Widgets are React components that provide complete functionality for common enterprise app workflows. 1417 | 1418 | Generate a widget token scoped to an organization and user with the specified scopes. 1419 | 1420 | #### `Parameters` 1421 | 1422 | #### `Returns ``object` 1423 | ```