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

# Create a user ID

> This endpoint generates a new user ID that can be used to identify a user within Permutive.

 When you're not using an SDK, and you're interacting with this endpoint directly, it is your responsibility to store a user's ID. This endpoint responds with a Permtive user ID that can be used to identify a user within Permutive, to be stored by the client.



## OpenAPI

````yaml POST /users
openapi: 3.1.0
info:
  title: Identity API
  version: v2
servers:
  - url: https://api.permutive.app/v2.0
security: []
paths:
  /users:
    post:
      tags:
        - v2.0
      summary: Create a user ID
      description: >-
        This endpoint generates a new user ID that can be used to identify a
        user within Permutive.

         When you're not using an SDK, and you're interacting with this endpoint directly, it is your responsibility to store a user's ID. This endpoint responds with a Permtive user ID that can be used to identify a user within Permutive, to be stored by the client.
      operationId: createUserId
      responses:
        '200':
          description: New user ID created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewUserId'
              example:
                id: 2008c38f-dece-4570-976d-87593ed001c3
        '401':
          description: 'Unauthorized request: invalid or missing API key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              examples:
                Invalid API key:
                  summary: Invalid API key
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    error:
                      status: Unauthorized
                      code: 2000
                      message: The API key provided is invalid.
                      docs: https://docs.permutive.com/api/errors
                Missing authentication:
                  summary: Missing authentication
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    error:
                      status: Unauthorized
                      code: 2004
                      message: >-
                        The resource requires authentication, which was not
                        supplied with the request.
                      docs: https://docs.permutive.com/api/errors
        '500':
          description: 'Internal server error: unexpected error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              example:
                request_id: 550e8400-e29b-41d4-a716-446655440000
                error:
                  status: InternalServerError
                  code: 5000
                  message: >-
                    An error of unspecified nature was encountered while
                    processing your request. Feel free to get in touch with us
                    at support@permutive.com referencing the Request ID.
                  docs: https://docs.permutive.com/api/errors
      security:
        - Header: []
        - Parameter: []
components:
  schemas:
    NewUserId:
      title: User ID response
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The newly generated Permutive user ID.
    HttpErrorResponse:
      title: HttpErrorResponse
      type: object
      required:
        - request_id
        - error
      properties:
        request_id:
          $ref: '#/components/schemas/RequestId'
        error:
          type: object
          description: Details of the error that occurred.
          required:
            - status
            - code
            - message
            - docs
          properties:
            status:
              type: string
              enum:
                - BadRequest
                - Unauthorized
                - NotFound
                - Conflict
                - Gone
                - InternalServerError
                - Forbidden
              description: The type of error that occurred.
            code:
              type: integer
              format: int32
              description: A numeric code that identifies the error.
            message:
              type: string
              description: A human-readable message describing the error.
            docs:
              type: string
              format: uri
              description: A URL to the documentation for the error.
            cause:
              type: string
              description: >-
                A human-readable message describing additional details of the
                error.
    RequestId:
      title: RequestId
      type: string
      format: uuid
      description: A unique identifier for the request that caused the error.
  securitySchemes:
    Header:
      type: apiKey
      name: X-API-Key
      in: header
    Parameter:
      type: apiKey
      name: k
      in: query

````