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

# Identify user

> Creates a new user on first call, keeps profile data in sync on subsequent calls,
and returns a short-lived sign-in token for WebView SSO.




## OpenAPI

````yaml /openapi.yaml post /api/v1/users/identify
openapi: 3.0.3
info:
  title: LearnInk API
  version: 1.0.0
  description: >
    LearnInk public API for identifying users (SSO token issuance) and user
    deletion.
servers:
  - url: https://my.learn.ink
security:
  - bearerAuth: []
tags:
  - name: Users
    description: User identification and lifecycle.
paths:
  /api/v1/users/identify:
    post:
      tags:
        - Users
      summary: Identify user
      description: >
        Creates a new user on first call, keeps profile data in sync on
        subsequent calls,

        and returns a short-lived sign-in token for WebView SSO.
      operationId: identifyUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentifyUserRequest'
            example:
              id: your_unique_user_id
              orgId: acme
              data:
                firstName: Mary
                lastName: Kamau
                country: Kenya
                region: Kisumu
                sex: female
                ageBracket: 18-24
                userGroups:
                  - field-agents
                  - nairobi-region
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentifyUserResponse'
              example:
                id: your_unique_user_id
                data:
                  userId: a_unique_id
                  registrationStatus: registered
                  lastActive: '2025-08-14T15:12:34+00:00'
                  registeredAt: '2025-05-02T09:23:32+00:00'
                  firstName: Mary
                  lastName: Kamau
                  country: Kenya
                  region: Kisumu
                  sex: female
                  ageBracket: 18-24
                  userGroups:
                    - field-agents
                    - nairobi-region
                  learningPathId: id1234
                  learningPathName: Field Agent Onboarding
                  learningPathStartDate: '2025-08-12'
                  learningPathDueDate: '2025-08-15'
                  learningPathCompletedAt: '2025-08-14T14:42:46+00:00'
                token: a_unique_sign_in_token
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 400
                message: Invalid request parameters
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 403
                message: Forbidden
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 500
                message: Internal server error
      security:
        - bearerAuth: []
components:
  schemas:
    IdentifyUserRequest:
      type: object
      required:
        - id
        - orgId
      properties:
        id:
          type: string
          description: Your unique identifier for this user.
        orgId:
          type: string
          description: Your LearnInk organisation ID.
        data:
          $ref: '#/components/schemas/UserProfileInput'
      additionalProperties: false
    IdentifyUserResponse:
      type: object
      required:
        - id
        - data
        - token
      properties:
        id:
          type: string
          description: The user identifier you passed in the request.
        data:
          $ref: '#/components/schemas/UserProfile'
        token:
          type: string
          description: A short-lived sign-in token. Use immediately — do not cache.
      additionalProperties: false
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
        message:
          type: string
      additionalProperties: false
    UserProfileInput:
      type: object
      description: Optional user profile data to create or update.
      properties:
        firstName:
          type: string
          description: The user's first name.
        lastName:
          type: string
          description: The user's last name.
        country:
          type: string
          description: The country the user is located in.
        region:
          type: string
          description: The region the user is located in.
        sex:
          type: string
          enum:
            - male
            - female
          description: The user's gender.
        ageBracket:
          type: string
          enum:
            - 18-24
            - 25-34
            - 35-44
            - 45-54
            - 55-64
            - 65+
          description: The user's age bracket.
        userGroups:
          type: array
          items:
            type: string
          description: IDs of user groups to assign to this user.
      additionalProperties: false
    UserProfile:
      type: object
      required:
        - userId
        - registrationStatus
        - userGroups
      properties:
        userId:
          type: string
          description: LearnInk's internal unique ID for this user.
        registrationStatus:
          type: string
          enum:
            - registered
            - unregistered
            - archived
        lastActive:
          type: string
          format: date-time
          nullable: true
        registeredAt:
          type: string
          format: date-time
          nullable: true
        firstName:
          type: string
          nullable: true
        lastName:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        region:
          type: string
          nullable: true
        sex:
          type: string
          enum:
            - male
            - female
          nullable: true
        ageBracket:
          type: string
          nullable: true
        userGroups:
          type: array
          items:
            type: string
        learningPathId:
          type: string
          nullable: true
        learningPathName:
          type: string
          nullable: true
        learningPathStartDate:
          type: string
          format: date
          nullable: true
        learningPathDueDate:
          type: string
          format: date
          nullable: true
        learningPathCompletedAt:
          type: string
          format: date-time
          nullable: true
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key

````