Authentication

Whatsapp Login

post

Authenticate users with WhatsApp.

Authorizations

APIKeyHeader

X-Tenant-IDstringRequired

Body

application/json

WhatsApp authentication request.

whatsapp_idstringRequired

profile_nameany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Login Response model.

422

Validation Error

application/json

post

/auth/whatsapp/login

HTTPcURLJavaScriptPython

POST /auth/whatsapp/login HTTP/1.1
X-Tenant-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 44

{
  "whatsapp_id": "text",
  "profile_name": "text"
}

{
  "user": {
    "id": "text",
    "username": "text",
    "email": "text",
    "display_name": "text",
    "roles": [
      "text"
    ],
    "permissions": [
      "text"
    ],
    "provider": "text",
    "picture": "text",
    "phone_number": "text",
    "is_verified": false,
    "tenants": [
      {
        "id": "text",
        "name": "text"
      }
    ],
    "selected_tenant": {
      "id": "text",
      "name": "text"
    },
    "is_guest": false,
    "is_sdk": false,
    "is_whatsapp": false
  },
  "token": {
    "access_token": "text",
    "token_type": "bearer"
  }
}

Whatsapp Register

post

Register new users with WhatsApp.

Authorizations

APIKeyHeader

X-Tenant-IDstringRequired

Body

application/json

WhatsApp register request.

whatsapp_idstringRequired

emailstringRequired

profile_nameany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Phone and email verification response model.

Attributes: challenge_id: Unique identifier for the verification challenge expires_at: Timestamp when the verification code expires user_detail: User details including username and display name cooldown: Cooldown period in seconds before next resend is allowed

challenge_idstringRequired

Unique challenge ID for verification

expires_atstring · date-timeRequired

When the verification code expires

cooldownintegerRequired

Cooldown period in seconds

422

Validation Error

application/json

post

/auth/whatsapp/register

HTTPcURLJavaScriptPython

POST /auth/whatsapp/register HTTP/1.1
X-Tenant-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 59

{
  "whatsapp_id": "text",
  "email": "text",
  "profile_name": "text"
}

{
  "challenge_id": "text",
  "expires_at": "2026-04-02T19:08:23.835Z",
  "user_detail": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "cooldown": 1
}

Whatsapp Login V2

post

Authenticate users with WhatsApp.

Authorizations

APIKeyHeader

X-Tenant-IDstringRequired

Body

application/json

WhatsApp authentication request.

whatsapp_idstringRequired

profile_nameany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Admin User model.

idstringRequired

usernamestringRequired

auth_idany ofOptional

stringOptional

or

nullOptional

display_nameany ofOptional

stringOptional

or

nullOptional

bosa_secretany ofOptional

stringOptional

or

nullOptional

pictureany ofOptional

stringOptional

or

nullOptional

emailany ofOptional

stringOptional

or

nullOptional

phone_numberany ofOptional

stringOptional

or

nullOptional

is_verifiedbooleanOptionalDefault: false

use_memorybooleanOptionalDefault: false

use_personalizationbooleanOptionalDefault: false

is_activebooleanOptionalDefault: true

user_domainany ofOptional

or

nullOptional

account_typeany ofOptional

string · enumOptional

Account type.

Possible values:

or

nullOptional

422

Validation Error

application/json

post

/auth/whatsapp/v2/login

HTTPcURLJavaScriptPython

POST /auth/whatsapp/v2/login HTTP/1.1
X-Tenant-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 44

{
  "whatsapp_id": "text",
  "profile_name": "text"
}

{
  "id": "text",
  "username": "text",
  "auth_id": "text",
  "display_name": "text",
  "bosa_secret": "text",
  "picture": "text",
  "email": "text",
  "phone_number": "text",
  "is_verified": false,
  "use_memory": false,
  "use_personalization": false,
  "is_active": true,
  "roles": [
    {
      "id": "text",
      "name": "text",
      "display_name": "text"
    }
  ],
  "user_domain": {
    "id": "text",
    "name": "text",
    "domain": "text",
    "chatbots": [
      {
        "created_at": "2026-04-02T19:08:23.835Z",
        "updated_at": "2026-04-02T19:08:23.835Z",
        "creator": {
          "id": "text",
          "username": "text",
          "display_name": "text"
        },
        "updater": {
          "id": "text",
          "username": "text",
          "display_name": "text"
        },
        "id": "text",
        "chatbot_id": "text",
        "chatbot_name": "text",
        "description": "text",
        "preset_id": "text",
        "pipeline_id": "text",
        "knowledge_base_id": "text",
        "prompt_builder_catalog_id": "text",
        "lmrp_catalog_id": "text",
        "organization_id": "text",
        "recommended_questions": [
          {
            "category": "text",
            "question": "text"
          }
        ],
        "supported_agent_ids": [
          "text"
        ],
        "is_question_library": false,
        "question_library_source": "FAQ",
        "display_type": "BY_ORDER",
        "click_behaviour": "SEND",
        "max_question_show": 1,
        "light_logo_url": "text",
        "dark_logo_url": "text",
        "use_tenant_logo": false,
        "show_app_logo": false,
        "preset": {
          "created_at": "2026-04-02T19:08:23.835Z",
          "updated_at": "2026-04-02T19:08:23.835Z",
          "creator": {
            "id": "text",
            "username": "text",
            "display_name": "text"
          },
          "updater": {
            "id": "text",
            "username": "text",
            "display_name": "text"
          },
          "id": "text",
          "pipeline_id": "text",
          "pipeline_preset_id": "text",
          "pipeline": {
            "id": "text",
            "name": "text",
            "type": "RAGO",
            "display_name": "text",
            "description": "text",
            "is_active": true,
            "is_internal": false,
            "metadata_": "text",
            "components": [
              {
                "id": "text",
                "name": "text",
                "display_name": "text",
                "description": "text"
              }
            ],
            "config_fields": [
              {
                "id": "text",
                "component_id": "text",
                "name": "text",
                "type": "text",
                "constraints": "text",
                "default_value": "text",
                "ui_type": "text",
                "dropdown_source": "text",
                "dropdown_key": "text",
                "dropdown_value": "text",
                "dropdown_filter": "text",
                "level": "text",
                "category_id": "text",
                "category": {
                  "id": "text",
                  "name": "text",
                  "order": 1
                }
              }
            ]
          }
        },
        "knowledge_base": {
          "created_at": "2026-04-02T19:08:23.835Z",
          "updated_at": "2026-04-02T19:08:23.835Z",
          "creator": {
            "id": "text",
            "username": "text",
            "display_name": "text"
          },
          "updater": {
            "id": "text",
            "username": "text",
            "display_name": "text"
          },
          "id": "text",
          "knowledge_base_id": "text",
          "knowledge_base_name": "text",
          "knowledge_base_description": "text",
          "index_name": "text",
          "dpo_preset_id": "text",
          "ttl": 1,
          "max_faq": 1,
          "is_processing_answer": true,
          "is_active": true,
          "smart_search_id": "text",
          "config": "text",
          "type": "text",
          "dpo_preset": {
            "created_at": "2026-04-02T19:08:23.835Z",
            "updated_at": "2026-04-02T19:08:23.835Z",
            "creator": {
              "id": "text",
              "username": "text",
              "display_name": "text"
            },
            "updater": {
              "id": "text",
              "username": "text",
              "display_name": "text"
            },
            "id": "text",
            "pipeline_id": "text",
            "pipeline_preset_id": "text",
            "pipeline": {
              "id": "text",
              "name": "text",
              "type": "RAGO",
              "display_name": "text",
              "description": "text",
              "is_active": true,
              "is_internal": false,
              "metadata_": "text",
              "components": [
                {
                  "id": "text",
                  "name": "text",
                  "display_name": "text",
                  "description": "text"
                }
              ],
              "config_fields": [
                {
                  "id": "text",
                  "component_id": "text",
                  "name": "text",
                  "type": "text",
                  "constraints": "text",
                  "default_value": "text",
                  "ui_type": "text",
                  "dropdown_source": "text",
                  "dropdown_key": "text",
                  "dropdown_value": "text",
                  "dropdown_filter": "text",
                  "level": "text",
                  "category_id": "text",
                  "category": {
                    "id": "text",
                    "name": "text",
                    "order": 1
                  }
                }
              ]
            }
          },
          "chatbots": [
            {
              "chatbot_id": "text",
              "chatbot_name": "text"
            }
          ],
          "knowledge_stores": [
            {
              "id": "text",
              "knowledge_base_id": "text",
              "name": "text",
              "type": "text",
              "index_name": "text",
              "dpo_preset_id": "text",
              "smart_search_id": "text",
              "config": "text",
              "is_active": true,
              "dpo_preset": {
                "created_at": "2026-04-02T19:08:23.835Z",
                "updated_at": "2026-04-02T19:08:23.835Z",
                "creator": {
                  "id": "text",
                  "username": "text",
                  "display_name": "text"
                },
                "updater": {
                  "id": "text",
                  "username": "text",
                  "display_name": "text"
                },
                "id": "text",
                "pipeline_id": "text",
                "pipeline_preset_id": "text",
                "pipeline": {
                  "id": "text",
                  "name": "text",
                  "type": "RAGO",
                  "display_name": "text",
                  "description": "text",
                  "is_active": true,
                  "is_internal": false,
                  "metadata_": "text",
                  "components": [
                    {
                      "id": "text",
                      "name": "text",
                      "display_name": "text",
                      "description": "text"
                    }
                  ],
                  "config_fields": [
                    {
                      "id": "text",
                      "component_id": "text",
                      "name": "text",
                      "type": "text",
                      "constraints": "text",
                      "default_value": "text",
                      "ui_type": "text",
                      "dropdown_source": "text",
                      "dropdown_key": "text",
                      "dropdown_value": "text",
                      "dropdown_filter": "text",
                      "level": "text",
                      "category_id": "text",
                      "category": {
                        "id": "text",
                        "name": "text",
                        "order": 1
                      }
                    }
                  ]
                }
              }
            }
          ]
        },
        "prompt_builder_catalog": {
          "id": "text",
          "name": "text",
          "description": "text",
          "is_override": false,
          "level": "CHATBOT",
          "level_entity_id": "text",
          "prompt_builder_catalog_entries": [
            {
              "created_at": "2026-04-02T19:08:23.835Z",
              "updated_at": "2026-04-02T19:08:23.835Z",
              "creator": {
                "id": "text",
                "username": "text",
                "display_name": "text"
              },
              "updater": {
                "id": "text",
                "username": "text",
                "display_name": "text"
              },
              "id": "text",
              "prompt_builder_catalog_id": "text",
              "name": "text",
              "scope": "text",
              "type": "text",
              "model": "text",
              "system_instruction": "text",
              "user_instruction": "text",
              "prompt_template_group_id": "text",
              "prompt_template_group_name": "text"
            }
          ]
        },
        "lmrp_catalog": {
          "id": "text",
          "name": "text",
          "description": "text",
          "is_override": false,
          "level": "CHATBOT",
          "level_entity_id": "text",
          "lmrp_catalog_entries": [
            {
              "created_at": "2026-04-02T19:08:23.835Z",
              "updated_at": "2026-04-02T19:08:23.835Z",
              "creator": {
                "id": "text",
                "username": "text",
                "display_name": "text"
              },
              "updater": {
                "id": "text",
                "username": "text",
                "display_name": "text"
              },
              "id": "text",
              "lmrp_catalog_id": "text",
              "name": "text",
              "scope": "text",
              "prompt_builder_type": "text",
              "prompt_builder_kwargs": "text",
              "prompt_builder_system_template": "text",
              "prompt_builder_user_template": "text",
              "model_id": "text",
              "output_parser_type": "text",
              "output_parser_kwargs": "text"
            }
          ]
        },
        "connectors": [
          {
            "id": "text",
            "name": "text",
            "display_name": "text",
            "description": "text",
            "icon": "text",
            "is_active": true,
            "knowledge_source": false,
            "is_connected": false,
            "chatbots": [
              {
                "id": "text",
                "chatbot_id": "text",
                "chatbot_name": "text"
              }
            ]
          }
        ],
        "chatbot_connectors": [
          {
            "id": "text",
            "chatbot_id": "text",
            "connector_id": "text",
            "connector": {
              "id": "text",
              "name": "text",
              "display_name": "text",
              "description": "text",
              "icon": "text",
              "is_active": true,
              "knowledge_source": false,
              "is_connected": false,
              "chatbots": [
                {
                  "id": "text",
                  "chatbot_id": "text",
                  "chatbot_name": "text"
                }
              ]
            }
          }
        ],
        "phone_number": {
          "id": "text",
          "provider_id": "text",
          "phone_number": "text",
          "display_name": "text",
          "provider_metadata": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "is_active": true,
          "created_at": "2026-04-02T19:08:23.835Z",
          "updated_at": "2026-04-02T19:08:23.835Z",
          "provider": {
            "id": "text",
            "name": "text",
            "icon": "text",
            "client_id": "text",
            "client_secret": "text",
            "created_at": "2026-04-02T19:08:23.835Z",
            "updated_at": "2026-04-02T19:08:23.835Z"
          },
          "chatbots": [
            {
              "id": "text",
              "chatbot_id": "text",
              "chatbot_name": "text"
            }
          ]
        },
        "organization": {
          "id": "text",
          "name": "text",
          "slug": "text",
          "team_id": "text",
          "encrypt_messages_enabled": true,
          "crypto_normalized_mode": "PLAINTEXT",
          "support_contact_email": "text",
          "primary_color": "text",
          "secondary_color": "text",
          "accent_color": "text",
          "light_logo_url": "text",
          "dark_logo_url": "text",
          "light_icon_url": "text",
          "dark_icon_url": "text",
          "user_domains": [
            "text"
          ],
          "feedback_url": "text",
          "user_guide_url": "text",
          "admin_guide_url": "text",
          "created_at": "2026-04-02T19:08:23.835Z",
          "updated_at": "2026-04-02T19:08:23.835Z",
          "updated_by": "text"
        }
      }
    ],
    "is_active": true
  },
  "chatbots": [
    {
      "created_at": "2026-04-02T19:08:23.835Z",
      "updated_at": "2026-04-02T19:08:23.835Z",
      "creator": {
        "id": "text",
        "username": "text",
        "display_name": "text"
      },
      "updater": {
        "id": "text",
        "username": "text",
        "display_name": "text"
      },
      "id": "text",
      "chatbot_id": "text",
      "chatbot_name": "text",
      "description": "text",
      "preset_id": "text",
      "pipeline_id": "text",
      "knowledge_base_id": "text",
      "prompt_builder_catalog_id": "text",
      "lmrp_catalog_id": "text",
      "organization_id": "text",
      "recommended_questions": [
        {
          "category": "text",
          "question": "text"
        }
      ],
      "supported_agent_ids": [
        "text"
      ],
      "is_question_library": false,
      "question_library_source": "FAQ",
      "display_type": "BY_ORDER",
      "click_behaviour": "SEND",
      "max_question_show": 1,
      "light_logo_url": "text",
      "dark_logo_url": "text",
      "use_tenant_logo": false,
      "show_app_logo": false,
      "preset": {
        "created_at": "2026-04-02T19:08:23.835Z",
        "updated_at": "2026-04-02T19:08:23.835Z",
        "creator": {
          "id": "text",
          "username": "text",
          "display_name": "text"
        },
        "updater": {
          "id": "text",
          "username": "text",
          "display_name": "text"
        },
        "id": "text",
        "pipeline_id": "text",
        "pipeline_preset_id": "text",
        "pipeline": {
          "id": "text",
          "name": "text",
          "type": "RAGO",
          "display_name": "text",
          "description": "text",
          "is_active": true,
          "is_internal": false,
          "metadata_": "text",
          "components": [
            {
              "id": "text",
              "name": "text",
              "display_name": "text",
              "description": "text"
            }
          ],
          "config_fields": [
            {
              "id": "text",
              "component_id": "text",
              "name": "text",
              "type": "text",
              "constraints": "text",
              "default_value": "text",
              "ui_type": "text",
              "dropdown_source": "text",
              "dropdown_key": "text",
              "dropdown_value": "text",
              "dropdown_filter": "text",
              "level": "text",
              "category_id": "text",
              "category": {
                "id": "text",
                "name": "text",
                "order": 1
              }
            }
          ]
        }
      },
      "knowledge_base": {
        "created_at": "2026-04-02T19:08:23.835Z",
        "updated_at": "2026-04-02T19:08:23.835Z",
        "creator": {
          "id": "text",
          "username": "text",
          "display_name": "text"
        },
        "updater": {
          "id": "text",
          "username": "text",
          "display_name": "text"
        },
        "id": "text",
        "knowledge_base_id": "text",
        "knowledge_base_name": "text",
        "knowledge_base_description": "text",
        "index_name": "text",
        "dpo_preset_id": "text",
        "ttl": 1,
        "max_faq": 1,
        "is_processing_answer": true,
        "is_active": true,
        "smart_search_id": "text",
        "config": "text",
        "type": "text",
        "dpo_preset": {
          "created_at": "2026-04-02T19:08:23.835Z",
          "updated_at": "2026-04-02T19:08:23.835Z",
          "creator": {
            "id": "text",
            "username": "text",
            "display_name": "text"
          },
          "updater": {
            "id": "text",
            "username": "text",
            "display_name": "text"
          },
          "id": "text",
          "pipeline_id": "text",
          "pipeline_preset_id": "text",
          "pipeline": {
            "id": "text",
            "name": "text",
            "type": "RAGO",
            "display_name": "text",
            "description": "text",
            "is_active": true,
            "is_internal": false,
            "metadata_": "text",
            "components": [
              {
                "id": "text",
                "name": "text",
                "display_name": "text",
                "description": "text"
              }
            ],
            "config_fields": [
              {
                "id": "text",
                "component_id": "text",
                "name": "text",
                "type": "text",
                "constraints": "text",
                "default_value": "text",
                "ui_type": "text",
                "dropdown_source": "text",
                "dropdown_key": "text",
                "dropdown_value": "text",
                "dropdown_filter": "text",
                "level": "text",
                "category_id": "text",
                "category": {
                  "id": "text",
                  "name": "text",
                  "order": 1
                }
              }
            ]
          }
        },
        "chatbots": [
          {
            "chatbot_id": "text",
            "chatbot_name": "text"
          }
        ],
        "knowledge_stores": [
          {
            "id": "text",
            "knowledge_base_id": "text",
            "name": "text",
            "type": "text",
            "index_name": "text",
            "dpo_preset_id": "text",
            "smart_search_id": "text",
            "config": "text",
            "is_active": true,
            "dpo_preset": {
              "created_at": "2026-04-02T19:08:23.835Z",
              "updated_at": "2026-04-02T19:08:23.835Z",
              "creator": {
                "id": "text",
                "username": "text",
                "display_name": "text"
              },
              "updater": {
                "id": "text",
                "username": "text",
                "display_name": "text"
              },
              "id": "text",
              "pipeline_id": "text",
              "pipeline_preset_id": "text",
              "pipeline": {
                "id": "text",
                "name": "text",
                "type": "RAGO",
                "display_name": "text",
                "description": "text",
                "is_active": true,
                "is_internal": false,
                "metadata_": "text",
                "components": [
                  {
                    "id": "text",
                    "name": "text",
                    "display_name": "text",
                    "description": "text"
                  }
                ],
                "config_fields": [
                  {
                    "id": "text",
                    "component_id": "text",
                    "name": "text",
                    "type": "text",
                    "constraints": "text",
                    "default_value": "text",
                    "ui_type": "text",
                    "dropdown_source": "text",
                    "dropdown_key": "text",
                    "dropdown_value": "text",
                    "dropdown_filter": "text",
                    "level": "text",
                    "category_id": "text",
                    "category": {
                      "id": "text",
                      "name": "text",
                      "order": 1
                    }
                  }
                ]
              }
            }
          }
        ]
      },
      "prompt_builder_catalog": {
        "id": "text",
        "name": "text",
        "description": "text",
        "is_override": false,
        "level": "CHATBOT",
        "level_entity_id": "text",
        "prompt_builder_catalog_entries": [
          {
            "created_at": "2026-04-02T19:08:23.835Z",
            "updated_at": "2026-04-02T19:08:23.835Z",
            "creator": {
              "id": "text",
              "username": "text",
              "display_name": "text"
            },
            "updater": {
              "id": "text",
              "username": "text",
              "display_name": "text"
            },
            "id": "text",
            "prompt_builder_catalog_id": "text",
            "name": "text",
            "scope": "text",
            "type": "text",
            "model": "text",
            "system_instruction": "text",
            "user_instruction": "text",
            "prompt_template_group_id": "text",
            "prompt_template_group_name": "text"
          }
        ]
      },
      "lmrp_catalog": {
        "id": "text",
        "name": "text",
        "description": "text",
        "is_override": false,
        "level": "CHATBOT",
        "level_entity_id": "text",
        "lmrp_catalog_entries": [
          {
            "created_at": "2026-04-02T19:08:23.835Z",
            "updated_at": "2026-04-02T19:08:23.835Z",
            "creator": {
              "id": "text",
              "username": "text",
              "display_name": "text"
            },
            "updater": {
              "id": "text",
              "username": "text",
              "display_name": "text"
            },
            "id": "text",
            "lmrp_catalog_id": "text",
            "name": "text",
            "scope": "text",
            "prompt_builder_type": "text",
            "prompt_builder_kwargs": "text",
            "prompt_builder_system_template": "text",
            "prompt_builder_user_template": "text",
            "model_id": "text",
            "output_parser_type": "text",
            "output_parser_kwargs": "text"
          }
        ]
      },
      "connectors": [
        {
          "id": "text",
          "name": "text",
          "display_name": "text",
          "description": "text",
          "icon": "text",
          "is_active": true,
          "knowledge_source": false,
          "is_connected": false,
          "chatbots": [
            {
              "id": "text",
              "chatbot_id": "text",
              "chatbot_name": "text"
            }
          ]
        }
      ],
      "chatbot_connectors": [
        {
          "id": "text",
          "chatbot_id": "text",
          "connector_id": "text",
          "connector": {
            "id": "text",
            "name": "text",
            "display_name": "text",
            "description": "text",
            "icon": "text",
            "is_active": true,
            "knowledge_source": false,
            "is_connected": false,
            "chatbots": [
              {
                "id": "text",
                "chatbot_id": "text",
                "chatbot_name": "text"
              }
            ]
          }
        }
      ],
      "phone_number": {
        "id": "text",
        "provider_id": "text",
        "phone_number": "text",
        "display_name": "text",
        "provider_metadata": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "is_active": true,
        "created_at": "2026-04-02T19:08:23.835Z",
        "updated_at": "2026-04-02T19:08:23.835Z",
        "provider": {
          "id": "text",
          "name": "text",
          "icon": "text",
          "client_id": "text",
          "client_secret": "text",
          "created_at": "2026-04-02T19:08:23.835Z",
          "updated_at": "2026-04-02T19:08:23.835Z"
        },
        "chatbots": [
          {
            "id": "text",
            "chatbot_id": "text",
            "chatbot_name": "text"
          }
        ]
      },
      "organization": {
        "id": "text",
        "name": "text",
        "slug": "text",
        "team_id": "text",
        "encrypt_messages_enabled": true,
        "crypto_normalized_mode": "PLAINTEXT",
        "support_contact_email": "text",
        "primary_color": "text",
        "secondary_color": "text",
        "accent_color": "text",
        "light_logo_url": "text",
        "dark_logo_url": "text",
        "light_icon_url": "text",
        "dark_icon_url": "text",
        "user_domains": [
          "text"
        ],
        "feedback_url": "text",
        "user_guide_url": "text",
        "admin_guide_url": "text",
        "created_at": "2026-04-02T19:08:23.835Z",
        "updated_at": "2026-04-02T19:08:23.835Z",
        "updated_by": "text"
      }
    }
  ],
  "organizations": [
    {
      "id": "text",
      "name": "text",
      "slug": "text",
      "team_id": "text",
      "encrypt_messages_enabled": true,
      "crypto_normalized_mode": "PLAINTEXT"
    }
  ],
  "account_type": "regular"
}

Initiate Mobile OAuth Login

get

Initiates the mobile OAuth authentication flow by redirecting to StackAuth.

**Security Requirements:**
- Requires valid mobile API key in X-API-Key header
- Rate limited to prevent abuse

**Flow:**
1. Validates API key and parameters
2. Generates secure state parameter with CSRF protection
3. Constructs StackAuth OAuth URL
4. Redirects user to StackAuth for authentication

**After OAuth:**
User will be redirected to `/auth/mobile/callback` which handles token exchange
and redirects back to the mobile app with an exchange code.

Authorizations

APIKeyHeader

X-Tenant-IDstringRequired

Query parameters

providerstringRequired

OAuth provider (google, apple, discord, etc.)

Example: google

redirect_uristringRequired

Mobile app deep link URI for final redirect

Example: myapp://auth-callback

Responses

200

Successful Response

application/json

Other propertiesstringOptional

400

Invalid provider or redirect URI

401

Missing or invalid mobile API key

422

Validation Error

application/json

429

Rate limit exceeded

get

/auth/mobile/login

HTTPcURLJavaScriptPython

GET /auth/mobile/login?provider=text&redirect_uri=text HTTP/1.1
X-Tenant-ID: YOUR_API_KEY
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "text"
}

Handle OAuth Callback

get

Handles the OAuth callback from StackAuth and redirects to mobile app.

**Flow:**
1. Receives authorization code and state from StackAuth
2. Validates state parameter for CSRF protection
3. Exchanges authorization code for access token
4. Stores tokens temporarily in Redis with exchange code
5. Returns HTML page that redirects to mobile app with exchange code

**Security:**
- State parameter validation prevents CSRF attacks
- Exchange codes expire in 60 seconds
- One-time use codes prevent replay attacks

**Note:** This endpoint does not require API key as it's called by StackAuth.

Query parameters

codeany ofOptional

OAuth authorization code from StackAuth

stringOptional

or

nullOptional

stateany ofOptional

CSRF state parameter

stringOptional

or

nullOptional

errorany ofOptional

OAuth error if authentication failed

stringOptional

or

nullOptional

Responses

200

HTML page with mobile app redirect

text/html

stringOptional

400

Invalid or expired state parameter

422

Validation Error

application/json

500

OAuth processing failed

get

/auth/mobile/callback

HTTPcURLJavaScriptPython

GET /auth/mobile/callback HTTP/1.1
Accept: */*

text

Exchange Code for Tokens

post

Exchanges the exchange code for final authentication tokens and user data.

**Security Requirements:**
- Requires valid mobile API key in X-API-Key header
- Rate limited to prevent abuse
- Exchange codes are one-time use and expire in 60 seconds

**Flow:**
1. Validates API key and exchange code
2. Retrieves stored authentication data from Redis
3. Processes post-login flow (user creation, role assignment)
4. Returns complete authentication response

**Response includes:**
- StackAuth access and refresh tokens
- Complete user profile with roles and permissions
- Tenant information

Authorizations

APIKeyHeader

X-Tenant-IDstringRequired

Body

application/json

Mobile token exchange request model.

exchange_codestring · min: 1 · max: 64Required

Exchange code received from OAuth callback

Responses

200

Complete authentication response

application/json

Mobile authentication response model.

access_tokenstringRequired

StackAuth access token for API calls

refresh_tokenstringRequired

StackAuth refresh token for token renewal

expires_inintegerRequired

Token expiration time in seconds

token_typestringOptional

Token type (always Bearer for StackAuth)

Default: Bearer

400

Invalid or expired exchange code

401

Missing or invalid mobile API key

422

Validation Error

application/json

429

Rate limit exceeded

500

Token exchange failed

post

/auth/mobile/exchange

HTTPcURLJavaScriptPython

POST /auth/mobile/exchange HTTP/1.1
X-Tenant-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 24

{
  "exchange_code": "text"
}

{
  "access_token": "text",
  "refresh_token": "text",
  "expires_in": 1,
  "token_type": "Bearer",
  "user": {
    "id": "text",
    "username": "text",
    "email": "text",
    "display_name": "text",
    "roles": [
      "text"
    ],
    "permissions": [
      "text"
    ],
    "provider": "text",
    "picture": "text",
    "phone_number": "text",
    "is_verified": false,
    "tenants": [
      {
        "id": "text",
        "name": "text"
      }
    ],
    "selected_tenant": {
      "id": "text",
      "name": "text"
    },
    "is_guest": false,
    "is_sdk": false,
    "is_whatsapp": false
  }
}

Get Me

get

Get current authenticated user

Authorizations

OAuth2PasswordBearerAPIKeyHeader

OAuth2passwordRequired

Token URL:

cookie

__Secure-next-auth.session-tokenany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Current authenticated user model.

idany ofOptional

stringOptional

or

nullOptional

usernameany ofOptional

stringOptional

or

nullOptional

emailany ofOptional

stringOptional

or

nullOptional

display_nameany ofOptional

stringOptional

or

nullOptional

rolesstring[]Optional

permissionsstring[]Optional

providerany ofOptional

Authentication provider type

stringOptional

or

nullOptional

pictureany ofOptional

stringOptional

or

nullOptional

phone_numberany ofOptional

stringOptional

or

nullOptional

is_verifiedbooleanOptionalDefault: false

selected_tenantany ofOptional

or

nullOptional

is_guestbooleanOptionalDefault: false

is_sdkbooleanOptionalDefault: false

is_whatsappbooleanOptionalDefault: false

422

Validation Error

application/json

get

/auth/me

HTTPcURLJavaScriptPython

GET /auth/me HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "id": "text",
  "username": "text",
  "email": "text",
  "display_name": "text",
  "roles": [
    "text"
  ],
  "permissions": [
    "text"
  ],
  "provider": "text",
  "picture": "text",
  "phone_number": "text",
  "is_verified": false,
  "tenants": [
    {
      "id": "text",
      "name": "text"
    }
  ],
  "selected_tenant": {
    "id": "text",
    "name": "text"
  },
  "is_guest": false,
  "is_sdk": false,
  "is_whatsapp": false
}

Direct API login

post

Direct API login.

Body

application/json

Direct API authentication request.

usernamestringRequired

passwordstringRequired

Responses

200

Successful Response

application/json

Token model.

access_tokenstringRequired

token_typestringOptional

Token type

Default: bearer

422

Validation Error

application/json

post

/auth/direct-api-login

HTTPcURLJavaScriptPython

POST /auth/direct-api-login HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 37

{
  "username": "text",
  "password": "text"
}

{
  "access_token": "text",
  "token_type": "bearer"
}

Post auth login

post

Mandatory post-auth login endpoint to complete user registration in backend database.

This endpoint MUST be called after completing the OAuth/credential login flow with StackAuth to properly
store basic user data in the backend database and establish the link between StackAuth and
the backend user systems. This creates the necessary mapping for the application to function.

OAuth Flow Sequence:
    1. Frontend initiates OAuth flow: {stackauth_url}/api/v1/auth/oauth/authorize/{provider}
    2. User completes OAuth authentication with the provider (Google, GitHub, etc.)
    3. StackAuth processes the OAuth callback and creates/updates user in StackAuth DB
    4. **THIS ENDPOINT** must be called to:
       - Store basic user data in the backend database
       - Create the mapping between StackAuth user ID and backend user ID
       - Return the user profile for the frontend session

Credential Flow Sequence:
    1. Frontend initiates credential login flow: {stackauth_url}/api/v1/auth/password/sign-in
    2. StackAuth processes the credential login
    3. **THIS ENDPOINT** must be called to:
       - Fetch the user data from database based on the StackAuth user ID
       - Return the user profile for the frontend session

Why This Is Mandatory:
    - StackAuth DB and Backend DB are separate systems
    - Backend needs to store the StackAuth ID link for user identification
    - RBAC (roles/permissions) remain in StackAuth and are checked there
    - Required for proper user session management in the application

Authorizations

OAuth2PasswordBearerAPIKeyHeader

OAuth2passwordRequired

Token URL:

Path parameters

typestring · enumRequired

Post auth login type

Possible values:

Responses

200

Successful Response

application/json

Current authenticated user model.

idany ofOptional

stringOptional

or

nullOptional

usernameany ofOptional

stringOptional

or

nullOptional

emailany ofOptional

stringOptional

or

nullOptional

display_nameany ofOptional

stringOptional

or

nullOptional

rolesstring[]Optional

permissionsstring[]Optional

providerany ofOptional

Authentication provider type

stringOptional

or

nullOptional

pictureany ofOptional

stringOptional

or

nullOptional

phone_numberany ofOptional

stringOptional

or

nullOptional

is_verifiedbooleanOptionalDefault: false

selected_tenantany ofOptional

or

nullOptional

is_guestbooleanOptionalDefault: false

is_sdkbooleanOptionalDefault: false

is_whatsappbooleanOptionalDefault: false

422

Validation Error

application/json

post

/auth/{type}/post-login

HTTPcURLJavaScriptPython

POST /auth/{type}/post-login HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "id": "text",
  "username": "text",
  "email": "text",
  "display_name": "text",
  "roles": [
    "text"
  ],
  "permissions": [
    "text"
  ],
  "provider": "text",
  "picture": "text",
  "phone_number": "text",
  "is_verified": false,
  "tenants": [
    {
      "id": "text",
      "name": "text"
    }
  ],
  "selected_tenant": {
    "id": "text",
    "name": "text"
  },
  "is_guest": false,
  "is_sdk": false,
  "is_whatsapp": false
}

Initialize Stack Auth

get

Initialize Stack Auth

Authorizations

OAuth2PasswordBearerAPIKeyHeader

OAuth2passwordRequired

Token URL:

cookie

__Secure-next-auth.session-tokenany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Other propertiesany ofOptional

booleanOptional

or

integerOptional

422

Validation Error

application/json

get

/auth/initialize

HTTPcURLJavaScriptPython

GET /auth/initialize HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": true
}

Logout user

post

Logout user

Authorizations

OAuth2PasswordBearer

OAuth2passwordRequired

Token URL:

Responses

200

Successfully logged out.

application/json

Other propertiesstringOptional

401

Token is required

application/json

post

/auth/logout

HTTPcURLJavaScriptPython

POST /auth/logout HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "text"
}

Resolve username

post

Resolve username

Authorizations

OAuth2PasswordBearerAPIKeyHeader

OAuth2passwordRequired

Token URL:

cookie

__Secure-next-auth.session-tokenany ofOptional

stringOptional

or

nullOptional

Body

application/json

Resolve username request.

identifierstringRequired

Responses

200

Successful Response

application/json

Other propertiesstringOptional

422

Validation Error

application/json

post

/auth/resolve-username

HTTPcURLJavaScriptPython

POST /auth/resolve-username HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 21

{
  "identifier": "text"
}

{
  "ANY_ADDITIONAL_PROPERTY": "text"
}