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

# Email Verification

> **Port**: 9001 (public) - Called by Auth0 when a user verifies their email.

This endpoint is triggered when a user clicks the email verification link.
It activates the user account by setting their status to ACTIVE.

**Authentication**: Secured with Auth0 webhook secret via custom header.

**Important**: Always returns 200 OK to prevent Auth0 from retrying, even on errors.




## OpenAPI

````yaml POST /api/v1/webhooks/auth0/email-verified
openapi: 3.1.0
info:
  title: AION Authentication Service API
  description: >
    Authentication and user management service for the AION platform.


    This service provides:

    - JWT and API key validation

    - User profile management

    - API key lifecycle management

    - User invitation and team management


    ## Authentication


    Most endpoints require authentication via one of:

    - **Bearer Token (JWT)**: OAuth2/OIDC tokens from Auth0

    - **API Key**: Service-generated API keys for machine-to-machine
    authentication


    Protected endpoints also require the `x-account-id` header to specify the
    account context.


    ## Error Handling


    All errors follow a consistent format with error codes prefixed by category:

    - `AUTH_*`: Authentication errors

    - `USER_*`: User management errors

    - `ACCT_*`: Account errors

    - `ROLE_*`: Role/permission errors

    - `APIKEY_*`: API key errors

    - `GEN_*`: General errors
  version: 1.0.0
  contact:
    name: AION Intelligence
  license:
    name: Proprietary
servers:
  - url: http://localhost:9001
    description: Local development server (Public API)
  - url: http://localhost:9002
    description: Local development server (Private/Health endpoints - internal only)
  - url: https://api.aion.ai
    description: Production server (Public API)
  - url: https://api-internal.aion.ai
    description: Production server (Private/Health endpoints - internal network only)
security: []
tags:
  - name: Health
    description: >
      Service health and status endpoints.


      **IMPORTANT**: These endpoints are served on a separate private port (9002
      by default).

      They should NOT be exposed publicly and are intended for:

      - Kubernetes health probes (readiness/liveness)

      - Internal monitoring systems

      - Load balancer health checks
  - name: Authentication
    description: Authentication and credential validation
  - name: Webhooks
    description: Webhook endpoints for external services (Auth0)
  - name: User Profile
    description: User profile management
  - name: Users
    description: User management and invitations
  - name: API Keys
    description: API key lifecycle management
paths:
  /api/v1/webhooks/auth0/email-verified:
    post:
      tags:
        - Webhooks
      summary: Auth0 email verification webhook
      description: >
        **Port**: 9001 (public) - Called by Auth0 when a user verifies their
        email.


        This endpoint is triggered when a user clicks the email verification
        link.

        It activates the user account by setting their status to ACTIVE.


        **Authentication**: Secured with Auth0 webhook secret via custom header.


        **Important**: Always returns 200 OK to prevent Auth0 from retrying,
        even on errors.
      operationId: handleAuth0EmailVerified
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Auth0WebhookRequest'
            example:
              event: email_verified
              timestamp: '2024-01-15T10:35:00Z'
              user:
                user_id: auth0|abc123
                email: user@example.com
                name: John Doe
                picture: https://example.com/avatar.jpg
                email_verified: true
      responses:
        '200':
          description: Webhook received and processed (or acknowledged with error logged)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
              examples:
                success:
                  summary: Successfully processed
                  value:
                    received: true
                    processed_at: '2024-01-15T10:35:01Z'
                acknowledged:
                  summary: Acknowledged (error logged)
                  value:
                    received: true
      security:
        - webhookAuth: []
components:
  schemas:
    Auth0WebhookRequest:
      type: object
      description: Generic webhook payload from Auth0
      required:
        - event
        - user
      properties:
        event:
          type: string
          description: Event type (e.g., "user_signup", "email_verified")
          example: user_signup
        user:
          $ref: '#/components/schemas/Auth0WebhookUser'
        timestamp:
          type: string
          format: date-time
          description: When the event occurred in Auth0
          example: '2024-01-15T10:30:00Z'
    WebhookResponse:
      type: object
      description: >
        Standard webhook acknowledgment response.

        Always returns success to prevent webhook retries from external
        services.
      properties:
        received:
          type: boolean
          description: Whether the webhook was received
          example: true
        processed_at:
          type: string
          format: date-time
          description: UTC timestamp when webhook was processed (optional)
          example: '2024-01-15T10:30:01Z'
    Auth0WebhookUser:
      type: object
      description: User data in Auth0 webhook payload
      required:
        - user_id
        - email
      properties:
        user_id:
          type: string
          description: Auth0 user ID (sub claim, e.g., "auth0|abc123")
          example: auth0|abc123
        email:
          type: string
          format: email
          description: User's email address
          example: user@example.com
        name:
          type: string
          description: User's display name
          example: John Doe
        picture:
          type: string
          format: uri
          description: URL to user's profile picture
          example: https://example.com/avatar.jpg
        email_verified:
          type: boolean
          description: Whether the user's email is verified
          example: false
  securitySchemes:
    webhookAuth:
      type: apiKey
      in: header
      name: x-webhook-secret
      description: |
        Auth0 webhook secret for authenticating webhook requests.
        For local development only, use 'dev-bypass' to skip authentication.

````