--- schema_version: "1" id: 1dc8b7ee4f32fdd1f14e529c206f3528877f72c6bfb9734a360bde4d5321c4ac title: Users collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/users.md canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/users source_site: developer.salesforce.com content_type: documentation content_hash: dc67e8c1302021c66341bb2e417490961c2c068a34ac8d7616fca8fa4b008e09 products: - B2C Commerce API - Salesforce APIs --- Users # Users [Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/users/users-oas-v1-public.yaml) ## API Overview The Users API provides endpoints for managing Business Manager users and their access keys within Salesforce Commerce Cloud. ### Overview This API allows administrators to create, retrieve, update, and delete users. It also supports managing access keys for users, retrieving password expiration information, and changing user passwords. ### Key Features * **User Management**: Create, retrieve, update, and delete Business Manager users * **Access Key Management**: Create, retrieve, enable/disable, and delete access keys for users * **Password Management**: Retrieve password expiration information and change passwords * **User Listing**: Retrieve all users with no filtering ### Access Key Scopes Access keys can be created for the following scopes: * `WEBDAV_AND_STUDIO`: Access for WebDAV and Studio operations * `AGENT_USER_AND_OCAPI`: Access for Agent User and OCAPI operations * `STOREFRONT`: Access for storefront operations ### Use Cases * **Provisioning**: Create and configure Business Manager users programmatically * **Key Rotation**: Manage access keys for automated integrations * **Security Auditing**: Review user accounts and their access configurations * **Password Policies**: Monitor password expiration and enforce password changes ### Authentication This API requires OAuth 2.0 authentication with the appropriate scopes: * `sfcc.users` - Read access to user resources * `sfcc.users.rw` - Read and write access to user resources ### Best Practices 1. Use access keys instead of passwords for automated integrations 2. Regularly rotate access keys for security 3. Monitor password expiration dates and enforce timely password changes 4. Use the PATCH endpoint for partial updates instead of PUT for full overwrites 5. Only externally managed users can have access keys **Version:** 1.0.0 ## Servers * `https://{shortCode}.api.commercecloud.salesforce.com/merchant/users/v1` * `shortCode (default 123456gf)` ## Security * `AmOAuth2` (oauth2) OAuth 2.0 security scheme for Admin API access using Account Manager. Requires appropriate scopes for user management operations. * OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dw/oauth2/access\_token) * Scope sfcc.users: Read access to user resources * Scope sfcc.users.rw: Read and write access to user resources ## Operations ### GET Get Users `GET /organizations/{organizationId}/users` Operation ID: `getUsers`. Security: AmOAuth2 (sfcc.users, sfcc.users.rw). Retrieves all users with no filtering. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by _Example_ ``` f_ecom_zzxy_prd ``` * `select` (query, Select) _Example: select_ ``` (**) ``` * `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25. Default: `25`. Minimum: 1. Maximum: 200. * `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset. Default: `0`. Minimum: 0. #### Responses * **200** Returns the collection of users Media type: `application/json`. Schema: `UserSearch`. _Example: UserSearchResponse_ User collection Example of a user search response with `select=(**)`. ``` { "limit": 3, "offset": 0, "total": 3, "data": [ { "login": "admin-user", "email": "admin@example.com", "firstName": "John", "lastName": "Doe", "externalId": "ext-12345", "disabled": false, "locked": false, "lastLoginDate": "2024-10-14", "passwordExpirationDate": "2025-01-14T00:00:00.000Z", "passwordModificationDate": "2024-10-14T10:00:00.000Z", "preferredDataLocale": "en-US", "preferredUiLocale": "en-US", "roles": [ "Administrator" ] }, { "login": "editor-user", "email": "editor@example.com", "firstName": "Jane", "lastName": "Smith", "externalId": "ext-67890", "disabled": false, "locked": false, "lastLoginDate": "2024-10-13", "passwordExpirationDate": "2025-01-13T00:00:00.000Z", "passwordModificationDate": "2024-10-13T08:00:00.000Z", "preferredDataLocale": "en-US", "preferredUiLocale": "en-US", "roles": [ "ContentEditor" ] }, { "login": "manager-user", "email": "manager@example.com", "firstName": "Bob", "lastName": "Wilson", "externalId": "ext-11111", "disabled": true, "locked": false, "lastLoginDate": "2024-09-01", "passwordExpirationDate": "2024-12-01T00:00:00.000Z", "passwordModificationDate": "2024-09-01T07:00:00.000Z", "preferredDataLocale": "default", "preferredUiLocale": "default", "roles": [ "CustomManager" ] } ] } ``` ### GET Get User `GET /organizations/{organizationId}/users/{login}` Operation ID: `getUser`. Security: AmOAuth2 (sfcc.users, sfcc.users.rw). Retrieves a single user by their login. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by _Example_ ``` f_ecom_zzxy_prd ``` * `login` (path, string, required) The login of the user. Minimum length: 1. Maximum length: 256. Example: `admin-user`. #### Responses * **200** Returns the user details Media type: `application/json`. Schema: `User`. _Example: UserDetails_ Single user details Example of a successful retrieval of a single user ``` { "login": "admin-user", "email": "admin@example.com", "firstName": "John", "lastName": "Doe", "externalId": "ext-12345", "disabled": false, "locked": false, "lastLoginDate": "2024-10-14", "passwordExpirationDate": "2025-01-14T00:00:00.000Z", "passwordModificationDate": "2024-10-14T10:00:00.000Z", "preferredDataLocale": "en-US", "preferredUiLocale": "en-US", "roles": [ "Administrator" ] } ``` * **404** User not found Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UserNotFound_ User not found Example of an error when the specified user does not exist ``` { "title": "User Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/user-not-found", "detail": "No user with login 'nonexistent-user' could be found." } ``` ### PUT Create or Replace User `PUT /organizations/{organizationId}/users/{login}` Operation ID: `createOrReplaceUser`. Security: AmOAuth2 (sfcc.users.rw). Creates or overwrites a user. If a user with the given login already exists, the existing user will be overwritten. If no such login exists, a new user is created. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by _Example_ ``` f_ecom_zzxy_prd ``` * `login` (path, string, required) The login of the user. Minimum length: 1. Maximum length: 256. Example: `admin-user`. #### Request body (required) The user to create or replace Media type: `application/json`. Schema: `User`. _Example: CreateUser_ Create a user Example of creating a new Business Manager user ``` { "login": "new-user", "email": "newuser@example.com", "firstName": "Jane", "lastName": "Smith", "externalId": "ext-67890", "password": "SecurePassword123!", "preferredDataLocale": "en-US", "preferredUiLocale": "en-US" } ``` #### Responses * **200** The user was successfully updated Media type: `application/json`. Schema: `User`. _Example: UserCreated_ Newly created user Example of a successfully created user ``` { "login": "new-user", "email": "newuser@example.com", "firstName": "Jane", "lastName": "Smith", "externalId": "ext-67890", "disabled": false, "locked": false, "passwordExpirationDate": "2025-06-01T00:00:00.000Z", "passwordModificationDate": "2025-03-01T12:00:00.000Z", "preferredDataLocale": "en-US", "preferredUiLocale": "en-US", "roles": [] } ``` * **201** The user was successfully created Media type: `application/json`. Schema: `User`. _Example UserCreated: same as PUT /organizations/{organizationId}/users/{login} 200 response._ Newly created user Example of a successfully created user _Example: UserCreated_ Newly created user Example of a successfully created user * **400** Bad Request - Invalid user request Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BadRequest_ Bad request Example of an error when a required field constraint is violated ``` { "title": "Bad Request", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "detail": "An error occurred while decoding the request. There's a value constraint violation of property '$.email' in document 'User'." } ``` _Example: IdConflict_ ID conflict Example of an error when the ID in the request body does not match the ID in the URL ``` { "title": "Id Conflict", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/id-conflict", "detail": "The ID in the request body ('different-login') doesn't match the ID in the URL ('scapi-id-conflict-test')." } ``` _Example: LocalUserCreation_ Local user creation not allowed Example of an error when creating a local user is not allowed with the current server settings ``` { "title": "Local User Creation", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/local-user-creation", "detail": "The creation of a local Business Manager user isn't allowed with the current server settings." } ``` _Example: PasswordPolicyViolation_ Password policy violation Example of an error when the password does not meet policy requirements ``` { "title": "Password Policy Violation", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/password-policy-violation", "detail": "The provided new password doesn't meet the requirements." } ``` ### DELETE Delete User `DELETE /organizations/{organizationId}/users/{login}` Operation ID: `deleteUser`. Security: AmOAuth2 (sfcc.users.rw). Deletes a single user. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by _Example_ ``` f_ecom_zzxy_prd ``` * `login` (path, string, required) The login of the user. Minimum length: 1. Maximum length: 256. Example: `admin-user`. #### Responses * **204** The user was successfully deleted * **404** User not found Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UserNotFound_ User not found Example of an error when the specified user does not exist ``` { "title": "User Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/user-not-found", "detail": "No user with login 'nonexistent-user' could be found." } ``` ### PATCH Update User `PATCH /organizations/{organizationId}/users/{login}` Operation ID: `updateUser`. Security: AmOAuth2 (sfcc.users.rw). Updates a user. The locked flag and the user password cannot be updated with this resource. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by _Example_ ``` f_ecom_zzxy_prd ``` * `login` (path, string, required) The login of the user. Minimum length: 1. Maximum length: 256. Example: `admin-user`. #### Request body (required) The user fields to update Media type: `application/json`. Schema: `UserUpdateRequest`. _Example: UpdateUser_ Update a user Example of updating an existing user ``` { "email": "updated@example.com", "firstName": "Jane", "lastName": "Smith-Updated", "preferredDataLocale": "de-DE" } ``` #### Responses * **200** The user was successfully updated Media type: `application/json`. Schema: `User`. _Example: UserUpdated_ Updated user Example of a successfully updated user ``` { "login": "admin-user", "email": "updated@example.com", "firstName": "Jane", "lastName": "Smith-Updated", "externalId": "ext-12345", "disabled": false, "locked": false, "lastLoginDate": "2024-10-14", "passwordExpirationDate": "2025-01-14T00:00:00.000Z", "passwordModificationDate": "2024-10-14T10:00:00.000Z", "preferredDataLocale": "de-DE", "preferredUiLocale": "en-US", "roles": [ "Administrator" ] } ``` * **400** Bad Request - Invalid user update request Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example BadRequest: same as PUT /organizations/{organizationId}/users/{login} 400 response._ Bad request Example of an error when a required field constraint is violated _Example IdConflict: same as PUT /organizations/{organizationId}/users/{login} 400 response._ ID conflict Example of an error when the ID in the request body does not match the ID in the URL _Example: BadRequest_ Bad request Example of an error when a required field constraint is violated _Example: IdConflict_ ID conflict Example of an error when the ID in the request body does not match the ID in the URL * **404** User not found Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UserNotFound_ User not found Example of an error when the specified user does not exist ``` { "title": "User Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/user-not-found", "detail": "No user with login 'nonexistent-user' could be found." } ``` ## Schemas ### OrganizationId An identifier for the organization the request is being made by Type: `string`. Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`. ### Select The property selector declaring which fields are included into the response payload. You can specify a single field name, a comma-separated list of names or work with wildcards. You can also specify array operations and filter expressions. The actual selector value must be enclosed within parentheses. For more information, please read the documentation about property selectors [here](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html). Type: `string`. Minimum length: 1. Pattern: ^\[(\].\*\[)\]$. Example: `(name,id,variationAttributes.(**))`. ### UserSearch Document representing a collection of users. Includes all fields of `PaginatedResultBase`. * `data` (_array of User_, required) The collection of users. ### User Document representing a user. * `login` (_string_, required) The login of the user. Minimum length: 1. Maximum length: 256. Example: `admin-user`. * `password` (_string_) The password of the user. Maximum length: 256. Example: `password`. * `email` (_string_, required) The email address of the user. Maximum length: 256. Example: `admin@example.com`. * `firstName` (_string_) The first name of the user. Maximum length: 256. Example: `John`. * `lastName` (_string_) The last name of the user. Maximum length: 256. Example: `Doe`. * `externalId` (_string_) The external identifier for the user. Maximum length: 256. Example: `ext-12345`. * `disabled` (_boolean_) Indicates whether the user is disabled. Example: `false`. * `locked` (_boolean_) Indicates whether the user is locked. Example: `false`. * `lastLoginDate` (_string (date)_) The date of the user's last login. Example: `2024-10-14`. * `passwordExpirationDate` (_string (date-time)_) The date and time when the user's password expires. Example: `2025-01-14T00:00:00.000Z`. * `passwordModificationDate` (_string (date-time)_) The date and time when the user's password was last modified. Example: `2024-10-14T10:00:00.000Z`. * `preferredDataLocale` (_object_) The preferred data locale for the user. Includes all fields of `LocaleCode`. * `preferredUiLocale` (_object_) The preferred UI locale for the user. Includes all fields of `LocaleCode`. * `roles` (_array of string_) The list of role identifiers assigned to the user. Items: Maximum length: 256. Example: `Administrator`. ### ErrorResponse * `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization Maximum length: 256. Example: `You do not have enough credit`. * `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5. Maximum length: 2048. Example: `NotEnoughMoney`. * `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem. Example: `Your current balance is 30, but that costs 50`. * `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5. Maximum length: 2048. Example: `/account/12345/msgs/abc`. ### UserUpdateRequest Document representing a request to update a user. The locked flag and user password cannot be updated with this resource. * `email` (_string_) The email address of the user. Maximum length: 256. Example: `updated@example.com`. * `firstName` (_string_) The first name of the user. Maximum length: 256. Example: `Jane`. * `lastName` (_string_) The last name of the user. Maximum length: 256. Example: `Smith-Updated`. * `externalId` (_string_) The external identifier for the user. Maximum length: 256. Example: `ext-updated`. * `preferredDataLocale` (_object_) The preferred data locale for the user. Includes all fields of `LocaleCode`. * `preferredUiLocale` (_object_) The preferred UI locale for the user. Includes all fields of `LocaleCode`. ### PaginatedResultBase Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`. Includes all fields of `ResultBase`. * `offset` (_Offset_, required) ### LocaleCode A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified. One of: `LanguageCountry`, `LanguageCode`, `DefaultFallback`. ### ResultBase Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned. * `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema. Example: `10`. * `total` (_Total_, required) ### Offset The zero-based index of the first hit/data to include in the result. Type: `integer (int32)`. Default: `0`. Minimum: 0. Example: `0`. ### LanguageCountry A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'. Type: `string`. Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`. ### LanguageCode A two letter lowercase language code conforming to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard. Additionally, this may be used to submit requests with the header parameter `Accept-Language`, following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). Type: `string`. Pattern: ^\[a-z\]\[a-z\]$. Example: `en`. ### DefaultFallback A specialized value indicating the system default values for locales. Type: `string`. Default: `default`. Pattern: ^default$. Example: `default`. ### Total The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated. Type: `integer (int32)`. Default: `0`. Minimum: 0. Example: `10`.