> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Update user Linux username

> Change the organization-scoped Linux username without changing UID, GID or home directory.

<Info>
  Requires the IAM action **`workspace:UpdateUser`**. See [WORKSPACE permissions](/workspace/permissions) for the full list, what each one covers, and an example policy.
</Info>


## OpenAPI

````yaml /api-reference/specs/workspace.yaml patch /v1/users/{user_id}
openapi: 3.0.3
info:
  title: Basaltic Workspace API
  version: 1.0.0
  description: >
    Organization management: organizations, accounts, human users, users-only
    groups, and organization policies. Account IAM identities may receive
    explicitly delegated organization policies through this API. Personal
    authentication remains at the IAM endpoint.


    Organization resources are global and are resolved in the authenticated
    organization. Canonical CRNs are
    crn:workspace:::organization/<organization-uuid>/<type>/<name-or-uuid>.
    Organization policies are separate from account policies; shared system
    policies use crn:workspace:::policy/<name>.
  contact:
    name: Basaltic Support
    email: ping@basaltic.sh
  license:
    name: Proprietary
    url: https://basaltic.sh/terms
servers:
  - url: https://workspace.basaltic.sh
    description: Global API endpoint
security:
  - BearerAuth: []
paths:
  /v1/users/{user_id}:
    patch:
      tags:
        - Workspace
      summary: Update user Linux username
      description: >-
        Change the organization-scoped Linux username without changing UID, GID
        or home directory.
      operationId: updateUser
      parameters:
        - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdateRequest'
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - BearerAuth: []
components:
  parameters:
    UserId:
      name: user_id
      in: path
      description: User ID
      required: true
      schema:
        type: string
        format: uuid
      example: 550e8400-e29b-41d4-a716-446655440000
  schemas:
    UserUpdateRequest:
      type: object
      additionalProperties: false
      required:
        - linux_username
      properties:
        linux_username:
          $ref: '#/components/schemas/CustomLinuxUsername'
    User:
      type: object
      description: A platform user linked to the organization.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          example: 550e8400-e29b-41d4-a716-446655440000
        crn:
          type: string
          readOnly: true
          description: Cloud Resource Name
          example: >-
            crn:workspace:::organization/550e8400-e29b-41d4-a716-446655440000/user/550e8400-e29b-41d4-a716-446655440001
        email:
          type: string
          format: email
          readOnly: true
          example: john.doe@acme.com
        name:
          type: string
          readOnly: true
          example: John Doe
        linux_identity:
          $ref: '#/components/schemas/LinuxIdentity'
        added_at:
          type: string
          format: date-time
          readOnly: true
          example: '2026-01-15T09:30:00Z'
        tags:
          $ref: '#/components/schemas/Tags'
    CustomLinuxUsername:
      type: string
      minLength: 1
      maxLength: 32
      pattern: ^[a-z_][a-z0-9_-]{0,31}$
      description: >-
        Optional custom Linux login name, unique across users, service accounts
        and pending invitations in the organization. Reserved system names and
        the bsu_/bsa_ prefixes cannot be chosen. Omit on creation to generate a
        name. Renaming preserves UID, GID and home directory; existing sessions
        are not disconnected.
      example: deploy-bot
    LinuxIdentity:
      type: object
      description: >-
        Stable platform-managed identity. Primary GID equals UID. Removing and
        re-adding a membership allocates a new identity; retired IDs are never
        reused.
      required:
        - username
        - uid
        - gid
        - home_directory
      properties:
        home_directory:
          type: string
          readOnly: true
          description: >-
            Stable home path derived from the immutable numeric identity,
            unchanged by username edits.
          example: /home/bsu_200001
        username:
          type: string
          readOnly: true
          pattern: ^[a-z_][a-z0-9_-]{0,31}$
          example: bsu_200001
        uid:
          type: integer
          format: int32
          minimum: 200000
          maximum: 2000000000
          readOnly: true
        gid:
          type: integer
          format: int32
          minimum: 200000
          maximum: 2000000000
          readOnly: true
    Tags:
      type: object
      additionalProperties:
        type: string
      example:
        environment: production
        team: backend
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              description: Error code identifying the type of error
              example: INVALID_INPUT
            message:
              type: string
              description: Human-readable error message
              example: Invalid request parameters
            request_id:
              type: string
              format: uuid
              description: Request ID for debugging
              example: 550e8400-e29b-41d4-a716-446655440000
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INVALID_INPUT
              message: Invalid request parameters
              request_id: 550e8400-e29b-41d4-a716-446655440000
    Unauthorized:
      description: Authentication required or token invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Authentication required
              request_id: 550e8400-e29b-41d4-a716-446655440000
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ACCESS_DENIED
              message: You don't have permission to perform this action
              request_id: 550e8400-e29b-41d4-a716-446655440000
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: NOT_FOUND
              message: Resource not found
              request_id: 550e8400-e29b-41d4-a716-446655440000
    Conflict:
      description: Resource conflict (e.g., already exists, invalid state)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: CONFLICT
              message: Resource with this name already exists
              request_id: 550e8400-e29b-41d4-a716-446655440000
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_ERROR
              message: An internal error occurred
              request_id: 550e8400-e29b-41d4-a716-446655440000
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        An OAuth 2.0 bearer token, sent as `Authorization: Bearer <token>`.
        This is the recommended way to authenticate.

        Get one by exchanging a service account's access key pair at
        `POST /v1/oauth/token` with `grant_type=client_credentials`. It is the
        standard client-credentials grant, so any OAuth-aware library will
        obtain and refresh it for you.

        ```
        curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
          https://iam.basaltic.sh/v1/oauth/token
        ```

        Tokens last an hour by default. The same access key pair is separately
        your AWS SigV4 credential for the S3-compatible object endpoint, which
        speaks nothing else.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.