contentstack User Sessions API

openapi: 3.2.0
info:
  title: Contentstack Content Management User Sessions API
  description: The Contentstack Content Management API (CMA) provides programmatic access to manage all aspects of a Contentstack stack, including content types, entries, assets, environments, workflows, and users. It supports full CRUD operations using standard HTTP verbs and authenticates via management tokens or user session tokens. Developers use this API to automate content operations, build editorial tooling, migrate content between environments, and integrate Contentstack with third-party systems. It is available at version v3 under the api.contentstack.io base URL for the North America region.
  version: v3
  contact:
    name: Contentstack Support
    url: https://www.contentstack.com/contact
  termsOfService: https://www.contentstack.com/legal/terms-of-service
servers:
- url: https://api.contentstack.io/v3
  description: AWS North America Production Server
- url: https://eu-api.contentstack.com/v3
  description: AWS Europe Production Server
- url: https://au-api.contentstack.com/v3
  description: AWS Australia Production Server
- url: https://azure-na-api.contentstack.com/v3
  description: Azure North America Production Server
- url: https://azure-eu-api.contentstack.com/v3
  description: Azure Europe Production Server
security:
- authtokenAuth: []
- managementTokenAuth: []
tags:
- name: User Sessions
  description: Endpoints for authenticating users and managing session tokens within Contentstack.
paths:
  /user-session:
    post:
      operationId: loginUser
      summary: Log in a user
      description: Authenticates a user with their email and password and returns an authtoken for use in subsequent API requests. The authtoken is valid for the duration of the session.
      tags:
      - User Sessions
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Successful authentication with authtoken.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: logoutUser
      summary: Log out a user
      description: Invalidates the current user session and authtoken, signing the user out of all Contentstack sessions.
      tags:
      - User Sessions
      responses:
        '200':
          description: Successfully logged out.
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    User:
      type: object
      description: A Contentstack user account.
      properties:
        uid:
          type: string
          description: Unique identifier of the user.
        first_name:
          type: string
          description: User's first name.
        last_name:
          type: string
          description: User's last name.
        email:
          type: string
          format: email
          description: User's email address.
        authtoken:
          type: string
          description: Session authentication token. Only returned on login.
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the user account was created.
    LoginRequest:
      type: object
      description: Credentials for user authentication.
      required:
      - user
      properties:
        user:
          type: object
          description: User credential object.
          required:
          - email
          - password
          properties:
            email:
              type: string
              format: email
              description: The user's email address.
            password:
              type: string
              format: password
              description: The user's account password.
    LoginResponse:
      type: object
      description: Authentication response containing the user's authtoken.
      properties:
        user:
          $ref: '#/components/schemas/User'
    Error:
      type: object
      description: Standard error response.
      properties:
        error_message:
          type: string
          description: Human-readable description of the error.
        error_code:
          type: integer
          description: Numeric error code.
        errors:
          type: object
          description: Field-level validation errors.
  responses:
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request is malformed or contains invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    authtokenAuth:
      type: apiKey
      in: header
      name: authtoken
      description: User session token obtained from the login endpoint.
    managementTokenAuth:
      type: apiKey
      in: header
      name: authorization
      description: Management token in the format "Bearer {management_token}" for server-to-server authentication without user sessions.
externalDocs:
  description: Contentstack Content Management API Documentation
  url: https://www.contentstack.com/docs/developers/apis/content-management-api