---
openapi: 3.0.3
info:
  title: Braze REST API – Create new dashboard user account
  description: |
    ## Prerequisites

    To use this endpoint, you'll need a SCIM token. You'll use your service origin as the `X-Request-Origin` header. For more information, refer to [Automated user provisioning]({{site.baseurl}}/scim/automated_user_provisioning).

    ## Rate limit

    This endpoint has a rate limit of 20,000 requests per day, per company. This rate limit is shared with the `/scim/v2/Users/` PUT, GET, and DELETE endpoints as documented in [API rate limits]({{site.baseurl}}/api/api_limits).
  version: 1.0.0
  contact:
    name: Braze Support
    url: https://www.braze.com/docs/braze_support/
  license:
    name: Braze Documentation
    url: https://www.braze.com/docs/api/home/
servers:
  - url: https://rest.iad-01.braze.com
    description: US-01
  - url: https://rest.iad-02.braze.com
    description: US-02
  - url: https://rest.iad-03.braze.com
    description: US-03
  - url: https://rest.iad-04.braze.com
    description: US-04
  - url: https://rest.iad-05.braze.com
    description: US-05
  - url: https://rest.iad-06.braze.com
    description: US-06
  - url: https://rest.iad-07.braze.com
    description: US-07
  - url: https://rest.iad-08.braze.com
    description: US-08
  - url: https://rest.us-10.braze.com
    description: US-10
  - url: https://rest.fra-01.braze.eu
    description: EU-01
  - url: https://rest.fra-02.braze.eu
    description: EU-02
  - url: https://rest.au-01.braze.com
    description: AU-01
  - url: https://rest.id-01.braze.com
    description: ID-01
  - url: https://rest.jp-01.braze.com
    description: JP-01
  - url: https://rest.kr-01.braze.com
    description: KR-01
security:
- BearerAuth: []
paths:
  /scim/v2/Users:
    post:
      summary: Create new dashboard user account
      operationId: post_scim_v2_users_post_create_user_account
      parameters:
        - name: X-Request-Origin
          in: header
          required: true
          description: 'Your service origin, sent as `X-Request-Origin: YOUR-REQUEST-ORIGIN-HERE`. For more information, refer to [Automated user provisioning]({{site.baseurl}}/scim/automated_user_provisioning).'
          schema:
            type: string
          example: YOUR-REQUEST-ORIGIN-HERE
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserAccountRequest'
            examples:
              with_permission_set:
                summary: Roles, workspace and team permissions, and a permission set
                value:
                  schemas:
                  - urn:ietf:params:scim:schemas:core:2.0:User
                  userName: user@example.com
                  name:
                    givenName: Test
                    familyName: User
                  department: finance
                  permissions:
                    companyPermissions:
                    - manage_company_settings
                    roles:
                    - roleName: Test Role
                    - roleId: 1f16c016-8e44-48f3-9fd7-2b8d5d70d9bd
                    appGroup:
                    - appGroupName: Test Workspace
                      appGroupPermissions:
                      - view_campaigns
                      - view_canvases
                      team:
                      - teamName: Test Team
                        teamPermissions:
                        - edit_campaigns
                        - launch_campaigns
                        - edit_canvases
                        - launch_canvases
                    - appGroupName: Other Test Workspace
                      appGroupPermissionSets:
                      - appGroupPermissionSetName: Test Permission Set
              with_workspace_permissions:
                summary: Roles, workspace permissions, and team permissions
                value:
                  schemas:
                  - urn:ietf:params:scim:schemas:core:2.0:User
                  userName: user@example.com
                  name:
                    givenName: Test
                    familyName: User
                  department: finance
                  permissions:
                    companyPermissions:
                    - manage_company_settings
                    roles:
                    - roleName: Test Role
                    - roleId: 1f16c016-8e44-48f3-9fd7-2b8d5d70d9bd
                    appGroup:
                    - appGroupName: Test Workspace
                      appGroupPermissions:
                      - view_campaigns
                      - view_canvases
                      team:
                      - teamName: Test Team
                        teamPermissions:
                        - edit_campaigns
                        - launch_campaigns
                        - edit_canvases
                        - launch_canvases
      responses:
        "201":
          description: The request succeeded and the dashboard user account was created. No action needed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardUser'
              examples:
                success:
                  summary: Dashboard user account created
                  value:
                    schemas:
                    - urn:ietf:params:scim:schemas:core:2.0:User
                    id: dfa245b7-24195aec-887bb3ad-602b3340
                    userName: user@example.com
                    name:
                      givenName: Test
                      familyName: User
                    department: finance
                    lastSignInAt: NA
                    createdAt: 2024 Nov 11, 4:20 PM
                    permissions:
                      companyPermissions:
                      - manage_company_settings
                      roles:
                      - roleName: Test Role
                        roleId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                        appGroup:
                        - appGroupId: a1b2c3d4-e5f6-4a1b-8c2d-3e4f5a6b7c8d
                          appGroupName: Some Workspace
                          appGroupPermissions:
                          - view_campaigns
                          - view_canvases
                          team:
                          - teamId: 1f16c016-8e44-48f3-9fd7-2b8d5d70d9bd
                            teamName: Some Team
                            teamPermissions:
                            - edit_campaigns
                            - launch_campaigns
                            - edit_canvases
                            - launch_canvases
                      - roleName: Another Test Role
                        roleId: b2c3d4e5-f6a7-4b1c-9d2e-4f5a6b7c8d9e
                        appGroup:
                        - appGroupId: c3d4e5f6-a7b8-4c1d-8e2f-5a6b7c8d9e0f
                          appGroupName: Production Workspace
                          appGroupPermissionSets:
                          - appGroupPermissionSetName: A Permission Set
                            appGroupPermissionSetId: d4e5f6a7-b8c9-4d1e-9f2a-6b7c8d9e0f1a
                            permissions:
                            - view_campaigns
                            - edit_campaigns
                            - view_content_blocks
                      appGroup:
                      - appGroupId: a1b2c3d4-e5f6-4a1b-8c2d-3e4f5a6b7c8d
                        appGroupName: Test Workspace
                        appGroupPermissions:
                        - view_campaigns
                        - view_canvases
                        team:
                        - teamId: 1f16c016-8e44-48f3-9fd7-2b8d5d70d9bd
                          teamName: Test Team
                          teamPermissions:
                          - edit_campaigns
                          - launch_campaigns
                          - edit_canvases
                          - launch_canvases
                      - appGroupName: Other Test Workspace
                        appGroupPermissionSets:
                        - appGroupPermissionSetName: Test Permission Set
        "400":
          description: Bad request. The `permissions` object is invalid, such as an unknown permission, workspace, team, role, or permission set name. Correct the `permissions` object, then retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unparsable:
                  summary: The request body violates the schema
                  value:
                    schemas:
                    - urn:ietf:params:scim:api:messages:2.0:Error
                    status: 400
                    detail: Request is unparsable, syntactically incorrect, or violates schema.
        "401":
          description: |
            Unauthorized. The SCIM bearer token is missing or invalid, the request origin isn't recognized, your IP isn't allowlisted, or SCIM isn't enabled. Send a valid SCIM bearer token from an allowlisted IP, and confirm SCIM provisioning is enabled. To enable SCIM, contact your Braze account manager.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_request_origin:
                  summary: The X-Request-Origin header is missing
                  value:
                    schemas:
                    - urn:ietf:params:scim:api:messages:2.0:Error
                    status: 401
                    detail: 'Unauthorized: X-Request-Origin header is missing.'
                invalid_token:
                  summary: The SCIM token isn't valid
                  value:
                    schemas:
                    - urn:ietf:params:scim:api:messages:2.0:Error
                    status: 401
                    detail: 'Unauthorized: token not valid.'
                ip_not_allowlisted:
                  summary: The request IP isn't allowlisted
                  value:
                    schemas:
                    - urn:ietf:params:scim:api:messages:2.0:Error
                    status: 401
                    detail: 'Unauthorized: Request IP is not in the configured IP allowlist.'
                scim_not_enabled:
                  summary: SCIM API access isn't enabled
                  value:
                    schemas:
                    - urn:ietf:params:scim:api:messages:2.0:Error
                    status: 401
                    detail: 'Unauthorized: SCIM API access is not enabled.'
        "409":
          description: |
            Conflict. A user with this `userName` or email address already exists. Look up the existing user with the [Search for existing dashboard users endpoint]({{site.baseurl}}/api/endpoints/scim/get_search_existing_dashboard_user/), or update them instead.

            If a user with this `userName` or email address already exists in Braze, the endpoint will respond with:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                user_exists:
                  summary: The user already exists
                  value:
                    schemas:
                    - urn:ietf:params:scim:api:messages:2.0:Error
                    status: 409
                    detail: Failed to create duplicate User resource (Braze Developer)
        "429":
          description: |
            Rate limited. You exceeded the SCIM daily rate limit of 20,000 requests per day. Slow your request rate and retry later. See [API rate limits]({{site.baseurl}}/api/api_limits/).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                over_rate_limit:
                  summary: Over rate limit
                  value:
                    schemas:
                    - urn:ietf:params:scim:api:messages:2.0:Error
                    status: 429
                    detail: You have exceeded your limit of 20000 requests per day. Please contact your account executive to increase your limit. If you do not have their info, you may contact Braze directly at https://www.braze.com/contact/.
        5XX:
          description: |
            Internal server error. An unexpected error occurred on the Braze server. Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/). If the account can't be created, the `detail` is `Failed to create user`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: SCIM token
      description: |
        SCIM endpoints authenticate with a SCIM token, not a REST API key. Generate the token in the
        Braze dashboard at **Settings → Company Settings → Admin Settings → SCIM Provisioning**.
        Pass the token as `Authorization: Bearer YOUR-SCIM-TOKEN-HERE`, and send your service
        origin in the `X-Request-Origin` header.
  schemas:
    CreateUserAccountRequest:
      title: Create dashboard user account request
      type: object
      required: [schemas, userName, name]
      properties:
        schemas:
          type: array
          items:
            type: string
          description: Expected SCIM 2.0 schema name for the user object.
          example:
            - urn:ietf:params:scim:schemas:core:2.0:User
        userName:
          type: string
          description: The user's email address.
          example: user@example.com
        name:
          allOf:
            - $ref: '#/components/schemas/UserName'
          description: This object contains the user's given name and family name.
        department:
          type: string
          description: Valid department string from the [department string documentation]({{site.baseurl}}/api/objects_filters/scim_api_appendix/?sdktab=granular%20scim%20api#granularscimapi_department-strings). Omit or pass an empty string if unknown.
          example: finance
        permissions:
          allOf:
            - $ref: '#/components/schemas/Permissions'
          description: Permissions object as described in the [permissions object documentation]({{site.baseurl}}/api/objects_filters/scim_api_appendix). When omitted or empty, Braze gives the user the [default permission set]({{site.baseurl}}/user_guide/administer/global/user_management/automated_user_provisioning/#default-permissions-for-new-users) on the default workspace configured in **SCIM Provisioning**. The default set includes view permissions only.
    DashboardUser:
      title: Dashboard user account
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
          description: "Expected SCIM 2.0 schema name for the user object."
        id:
          type: string
          description: "ID generated by Braze that is used for searching and managing user accounts."
        userName:
          type: string
          description: "The user's email address."
        name:
          allOf:
            - $ref: '#/components/schemas/UserName'
          description: "This object contains the user's first name and family name."
        department:
          type: string
          description: "Valid department string from the [department string documentation]({{site.baseurl}}/api/objects_filters/scim_api_appendix)."
        createdAt:
          type: string
          description: "Date the user account was created in UTC. Returns `NA` when unset."
        lastSignInAt:
          type: string
          description: "Date of last successful sign-on in UTC. Returns `NA` when the user has not signed in. Format: `YYYY Mon DD, H:MM AM/PM`."
        permissions:
          allOf:
            - $ref: '#/components/schemas/Permissions'
          description: "Permissions object as described in the [permissions object documentation]({{site.baseurl}}/api/objects_filters/scim_api_appendix)."
    TeamPermissions:
      title: Team permissions
      type: object
      properties:
        teamId:
          type: string
        teamName:
          type: string
        teamPermissions:
          type: array
          items:
            type: string
    PermissionSet:
      title: Permission set
      type: object
      properties:
        appGroupPermissionSetName:
          type: string
        appGroupPermissionSetId:
          type: string
        permissions:
          type: array
          items:
            type: string
    WorkspacePermissions:
      title: Workspace permissions
      type: object
      properties:
        appGroupId:
          type: string
        appGroupName:
          type: string
        appGroupPermissions:
          type: array
          items:
            type: string
        team:
          type: array
          items:
            $ref: '#/components/schemas/TeamPermissions'
        appGroupPermissionSets:
          type: array
          items:
            $ref: '#/components/schemas/PermissionSet'
    Role:
      title: Role
      type: object
      properties:
        roleName:
          type: string
        roleId:
          type: string
        appGroup:
          type: array
          items:
            $ref: '#/components/schemas/WorkspacePermissions'
    Permissions:
      title: Permissions
      type: object
      properties:
        companyPermissions:
          type: array
          items:
            type: string
        roles:
          type: array
          items:
            $ref: '#/components/schemas/Role'
        appGroup:
          type: array
          items:
            $ref: '#/components/schemas/WorkspacePermissions'
    UserName:
      title: Name
      type: object
      properties:
        givenName:
          type: string
          example: Test
        familyName:
          type: string
          example: User
    ErrorResponse:
      title: Error
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
          description: SCIM error message schema.
          example:
            - urn:ietf:params:scim:api:messages:2.0:Error
        status:
          type: integer
          description: The HTTP status code of the error.
          example: 404
        detail:
          type: string
          description: The error message describing why the request failed.
