{ "openapi": "3.0.3", "info": { "title": "Willow SCIM API", "description": "SCIM 2.0 provisioning for Willow organizations, as used by Okta, Azure AD and\nother identity providers to synchronise users and groups.\n\n## Provenance\n\nThis specification was derived from the running service rather than written\nfrom scratch. The attribute definitions come from the service's own\n`/scim/v2/Schemas` endpoint; the envelope, resource and error shapes were\nobserved from live responses. Every read operation below has been executed\nagainst a real organization.\n\nThe write operations (`POST`, `PUT`, `PATCH`, `DELETE` on Users and Groups)\nare declared because `/scim/v2/ResourceTypes` advertises both resources and\n`ServiceProviderConfig` reports `patch.supported: true`. They follow\nRFC 7644. They have **not** been executed against a live organization —\ndoing so provisions real users — so treat their response shapes as derived\nfrom the specification rather than confirmed by observation.\n\n## Authentication\n\nUse an API token with the `admin:scim` scope, or any scope that includes it\n(`admin:write`, `all`):\n\n```\nAuthorization: Bearer wxt_xxxxx\n```\n\nNote that `ServiceProviderConfig` advertises HTTP Basic as the primary\nauthentication scheme. Basic is **not** accepted — it returns 401. Only\nBearer works. See [API Tokens](/docs/admin/api-tokens).\n\nOn-premises deployments may alternatively use the `AUTH_SECRET` environment\nvariable. See [SCIM Provisioning](/docs/admin/advanced-capabilities/scim).\n", "version": "1.0.0", "contact": { "name": "Willow Support", "url": "https://withwillow.ai" } }, "servers": [ { "url": "https://app.withwillow.ai", "description": "Your Willow instance" } ], "tags": [ { "name": "SCIM Discovery", "description": "Service metadata describing what this SCIM implementation supports" }, { "name": "SCIM Users", "description": "Provision and manage users from an identity provider" }, { "name": "SCIM Groups", "description": "Provision and manage groups from an identity provider" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/scim/v2/ServiceProviderConfig": { "get": { "operationId": "getScimServiceProviderConfig", "tags": [ "SCIM Discovery" ], "summary": "Service Provider Configuration", "description": "Describes the SCIM features this deployment supports. Identity providers\nread this before provisioning to decide which operations to use.\n", "responses": { "200": { "description": "Service configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimServiceProviderConfig" } } } }, "401": { "$ref": "#/components/responses/ScimUnauthorized" }, "403": { "$ref": "#/components/responses/ScimForbidden" } } } }, "/scim/v2/ResourceTypes": { "get": { "operationId": "listScimResourceTypes", "tags": [ "SCIM Discovery" ], "summary": "List Resource Types", "description": "The resource types this service exposes — User and Group.", "responses": { "200": { "description": "Resource types", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimListResponse" } } } }, "401": { "$ref": "#/components/responses/ScimUnauthorized" }, "403": { "$ref": "#/components/responses/ScimForbidden" } } } }, "/scim/v2/Schemas": { "get": { "operationId": "listScimSchemas", "tags": [ "SCIM Discovery" ], "summary": "List Schemas", "description": "Attribute definitions for each supported resource. This endpoint is the\nauthoritative source for the User and Group shapes below.\n", "responses": { "200": { "description": "Schema definitions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimListResponse" } } } }, "401": { "$ref": "#/components/responses/ScimUnauthorized" }, "403": { "$ref": "#/components/responses/ScimForbidden" } } } }, "/scim/v2/Users": { "get": { "operationId": "listScimUsers", "tags": [ "SCIM Users" ], "summary": "List Users", "parameters": [ { "name": "filter", "in": "query", "required": false, "description": "SCIM filter expression, for example `userName eq \"user@example.com\"`.\nFiltering is advertised as supported in ServiceProviderConfig.\n", "schema": { "type": "string" }, "example": "userName eq \"user@example.com\"" }, { "name": "startIndex", "in": "query", "required": false, "description": "1-based index of the first result to return.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "count", "in": "query", "required": false, "description": "Maximum number of results to return.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "A paged list of users", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ScimListResponse" }, { "type": "object", "properties": { "Resources": { "type": "array", "items": { "$ref": "#/components/schemas/ScimUser" } } } } ] } } } }, "401": { "$ref": "#/components/responses/ScimUnauthorized" }, "403": { "$ref": "#/components/responses/ScimForbidden" } } }, "post": { "operationId": "createScimUser", "tags": [ "SCIM Users" ], "summary": "Create User", "description": "Provisions a new user. Not verified against a live organization.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimUser" }, "example": { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "userName": "user@example.com", "displayName": "Example User", "name": { "givenName": "Example", "familyName": "User" }, "emails": [ { "value": "user@example.com", "primary": true, "type": "work" } ], "active": true } } } }, "responses": { "201": { "description": "User created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } } }, "400": { "$ref": "#/components/responses/ScimBadRequest" }, "401": { "$ref": "#/components/responses/ScimUnauthorized" }, "403": { "$ref": "#/components/responses/ScimForbidden" }, "409": { "$ref": "#/components/responses/ScimConflict" } } } }, "/scim/v2/Users/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The SCIM resource id, as returned in `id`.", "schema": { "type": "string" } } ], "get": { "operationId": "getScimUser", "tags": [ "SCIM Users" ], "summary": "Get User", "responses": { "200": { "description": "The user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } } }, "401": { "$ref": "#/components/responses/ScimUnauthorized" }, "403": { "$ref": "#/components/responses/ScimForbidden" }, "404": { "$ref": "#/components/responses/ScimNotFound" } } }, "put": { "operationId": "replaceScimUser", "tags": [ "SCIM Users" ], "summary": "Replace User", "description": "Full replacement of the resource. Not verified against a live organization.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } } }, "responses": { "200": { "description": "The updated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } } }, "400": { "$ref": "#/components/responses/ScimBadRequest" }, "401": { "$ref": "#/components/responses/ScimUnauthorized" }, "403": { "$ref": "#/components/responses/ScimForbidden" }, "404": { "$ref": "#/components/responses/ScimNotFound" } } }, "patch": { "operationId": "patchScimUser", "tags": [ "SCIM Users" ], "summary": "Patch User", "description": "Partial update using SCIM PatchOp. This is how identity providers\ndeactivate a user — `replace` on `active` with `false`. Not verified\nagainst a live organization.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimPatchOp" }, "example": { "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ], "Operations": [ { "op": "replace", "path": "active", "value": false } ] } } } }, "responses": { "200": { "description": "The updated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } } }, "400": { "$ref": "#/components/responses/ScimBadRequest" }, "401": { "$ref": "#/components/responses/ScimUnauthorized" }, "403": { "$ref": "#/components/responses/ScimForbidden" }, "404": { "$ref": "#/components/responses/ScimNotFound" } } }, "delete": { "operationId": "deleteScimUser", "tags": [ "SCIM Users" ], "summary": "Delete User", "description": "Deprovisions the user. Not verified against a live organization.", "responses": { "204": { "description": "User deleted" }, "401": { "$ref": "#/components/responses/ScimUnauthorized" }, "403": { "$ref": "#/components/responses/ScimForbidden" }, "404": { "$ref": "#/components/responses/ScimNotFound" } } } }, "/scim/v2/Groups": { "get": { "operationId": "listScimGroups", "tags": [ "SCIM Groups" ], "summary": "List Groups", "parameters": [ { "name": "filter", "in": "query", "required": false, "schema": { "type": "string" }, "example": "displayName eq \"Engineering\"" }, { "name": "startIndex", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "A paged list of groups", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ScimListResponse" }, { "type": "object", "properties": { "Resources": { "type": "array", "items": { "$ref": "#/components/schemas/ScimGroup" } } } } ] } } } }, "401": { "$ref": "#/components/responses/ScimUnauthorized" }, "403": { "$ref": "#/components/responses/ScimForbidden" } } }, "post": { "operationId": "createScimGroup", "tags": [ "SCIM Groups" ], "summary": "Create Group", "description": "Not verified against a live organization.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimGroup" }, "example": { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "Engineering" } } } }, "responses": { "201": { "description": "Group created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } } } }, "400": { "$ref": "#/components/responses/ScimBadRequest" }, "401": { "$ref": "#/components/responses/ScimUnauthorized" }, "403": { "$ref": "#/components/responses/ScimForbidden" }, "409": { "$ref": "#/components/responses/ScimConflict" } } } }, "/scim/v2/Groups/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getScimGroup", "tags": [ "SCIM Groups" ], "summary": "Get Group", "responses": { "200": { "description": "The group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } } } }, "401": { "$ref": "#/components/responses/ScimUnauthorized" }, "403": { "$ref": "#/components/responses/ScimForbidden" }, "404": { "$ref": "#/components/responses/ScimNotFound" } } }, "put": { "operationId": "replaceScimGroup", "tags": [ "SCIM Groups" ], "summary": "Replace Group", "description": "Not verified against a live organization.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } } } }, "responses": { "200": { "description": "The updated group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } } } }, "400": { "$ref": "#/components/responses/ScimBadRequest" }, "401": { "$ref": "#/components/responses/ScimUnauthorized" }, "403": { "$ref": "#/components/responses/ScimForbidden" }, "404": { "$ref": "#/components/responses/ScimNotFound" } } }, "patch": { "operationId": "patchScimGroup", "tags": [ "SCIM Groups" ], "summary": "Patch Group", "description": "Partial update using SCIM PatchOp. This is how identity providers add and\nremove group members. Not verified against a live organization.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimPatchOp" }, "example": { "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ], "Operations": [ { "op": "add", "path": "members", "value": [ { "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } ] } } } }, "responses": { "200": { "description": "The updated group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } } } }, "400": { "$ref": "#/components/responses/ScimBadRequest" }, "401": { "$ref": "#/components/responses/ScimUnauthorized" }, "403": { "$ref": "#/components/responses/ScimForbidden" }, "404": { "$ref": "#/components/responses/ScimNotFound" } } }, "delete": { "operationId": "deleteScimGroup", "tags": [ "SCIM Groups" ], "summary": "Delete Group", "description": "Not verified against a live organization.", "responses": { "204": { "description": "Group deleted" }, "401": { "$ref": "#/components/responses/ScimUnauthorized" }, "403": { "$ref": "#/components/responses/ScimForbidden" }, "404": { "$ref": "#/components/responses/ScimNotFound" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API token with the `admin:scim` scope, or a scope that includes it (`admin:write`, `all`). Tokens are prefixed with `wxt_`.\n" } }, "responses": { "ScimBadRequest": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimError" } } } }, "ScimUnauthorized": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimError" } } } }, "ScimForbidden": { "description": "The token lacks the `admin:scim` scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimError" }, "example": { "schemas": [ "urn:ietf:params:scim:api:messages:2.0:Error" ], "detail": "Token does not have the required scope", "status": "403" } } } }, "ScimNotFound": { "description": "No such resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimError" }, "example": { "schemas": [ "urn:ietf:params:scim:api:messages:2.0:Error" ], "detail": "User not found", "status": "404" } } } }, "ScimConflict": { "description": "A resource with that identifier already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimError" } } } } }, "schemas": { "ScimError": { "type": "object", "description": "RFC 7644 error response.", "properties": { "schemas": { "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:api:messages:2.0:Error" ] }, "detail": { "type": "string", "description": "Human-readable explanation." }, "status": { "type": "string", "description": "HTTP status as a string, per RFC 7644.", "example": "404" }, "scimType": { "type": "string", "description": "SCIM error keyword, when applicable." } } }, "ScimListResponse": { "type": "object", "description": "RFC 7644 list envelope.", "properties": { "schemas": { "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] }, "totalResults": { "type": "integer", "example": 30 }, "startIndex": { "type": "integer", "example": 1 }, "itemsPerPage": { "type": "integer", "example": 3 }, "Resources": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "ScimMeta": { "type": "object", "description": "Resource metadata. Read-only.", "properties": { "resourceType": { "type": "string", "example": "User" }, "created": { "type": "string", "format": "date-time" }, "lastModified": { "type": "string", "format": "date-time" }, "location": { "type": "string", "description": "Canonical URI of this resource." } } }, "ScimName": { "type": "object", "properties": { "formatted": { "type": "string", "example": "Example User" }, "givenName": { "type": "string", "example": "Example" }, "familyName": { "type": "string", "example": "User" } } }, "ScimEmail": { "type": "object", "properties": { "value": { "type": "string", "format": "email" }, "type": { "type": "string", "example": "work" }, "primary": { "type": "boolean", "example": true } } }, "ScimMember": { "type": "object", "description": "A group member reference.", "properties": { "value": { "type": "string", "description": "The member's SCIM user id." }, "$ref": { "type": "string", "description": "URI of the member resource." }, "display": { "type": "string", "description": "Advertised as a sub-attribute by /scim/v2/Schemas but not present on observed responses." } } }, "ScimUser": { "type": "object", "description": "Attribute set taken from the service's own /scim/v2/Schemas definition for urn:ietf:params:scim:schemas:core:2.0:User.", "required": [ "userName" ], "properties": { "schemas": { "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:schemas:core:2.0:User" ] }, "id": { "type": "string", "description": "Server-assigned identifier. Read-only." }, "externalId": { "type": "string", "description": "Identifier assigned by the provisioning client." }, "userName": { "type": "string", "description": "Unique login identifier. Required.", "example": "user@example.com" }, "name": { "$ref": "#/components/schemas/ScimName" }, "displayName": { "type": "string", "example": "Example User" }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/ScimEmail" } }, "active": { "type": "boolean", "description": "Whether the account is enabled. Providers deactivate by patching this to false.", "example": true }, "meta": { "$ref": "#/components/schemas/ScimMeta" } } }, "ScimGroup": { "type": "object", "description": "Attribute set taken from the service's own /scim/v2/Schemas definition for urn:ietf:params:scim:schemas:core:2.0:Group.", "required": [ "displayName" ], "properties": { "schemas": { "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ] }, "id": { "type": "string", "description": "Server-assigned identifier. Read-only." }, "externalId": { "type": "string", "description": "Identifier assigned by the provisioning client." }, "displayName": { "type": "string", "description": "Group name. Required.", "example": "Engineering" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/ScimMember" } }, "meta": { "$ref": "#/components/schemas/ScimMeta" } } }, "ScimServiceProviderConfig": { "type": "object", "properties": { "schemas": { "type": "array", "items": { "type": "string" } }, "documentationUri": { "type": "string", "example": "https://tools.ietf.org/html/rfc7644" }, "patch": { "$ref": "#/components/schemas/ScimSupported" }, "bulk": { "allOf": [ { "$ref": "#/components/schemas/ScimSupported" }, { "type": "object", "properties": { "maxOperations": { "type": "integer", "example": 0 }, "maxPayloadSize": { "type": "integer" } } } ] }, "filter": { "allOf": [ { "$ref": "#/components/schemas/ScimSupported" }, { "type": "object", "properties": { "maxResults": { "type": "integer" } } } ] }, "changePassword": { "$ref": "#/components/schemas/ScimSupported" }, "sort": { "$ref": "#/components/schemas/ScimSupported" }, "etag": { "$ref": "#/components/schemas/ScimSupported" }, "meta": { "$ref": "#/components/schemas/ScimMeta" }, "authenticationSchemes": { "type": "array", "description": "Advertised authentication schemes. Note that HTTP Basic is listed with `primary: true` but is not accepted — only Bearer works.", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "oauthbearertoken" }, "name": { "type": "string" }, "description": { "type": "string" }, "specUri": { "type": "string" }, "primary": { "type": "boolean" } } } } } }, "ScimSupported": { "type": "object", "properties": { "supported": { "type": "boolean" } } }, "ScimPatchOp": { "type": "object", "description": "RFC 7644 PatchOp request.", "required": [ "Operations" ], "properties": { "schemas": { "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ] }, "Operations": { "type": "array", "items": { "type": "object", "required": [ "op" ], "properties": { "op": { "type": "string", "enum": [ "add", "remove", "replace" ] }, "path": { "type": "string", "example": "active" }, "value": { "description": "Replacement value. Shape depends on the target attribute." } } } } } } } } }