Authentication

post

Authenticate users with WhatsApp.

Authorizations

X-Tenant-IDstringRequired

Body

WhatsApp authentication request.

whatsapp_idstringRequired

profile_nameany ofOptional

stringOptional

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

post

/auth/whatsapp/login

POST /auth/whatsapp/login HTTP/1.1
Host: 
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

Authorizations

X-Tenant-IDstringRequired

Body

WhatsApp register request.

whatsapp_idstringRequired

emailstringRequired

profile_nameany ofOptional

stringOptional

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

post

/auth/whatsapp/register

POST /auth/whatsapp/register HTTP/1.1
Host: 
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-01-13T03:34:10.853Z",
  "user_detail": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "cooldown": 1
}

post

Authenticate users with WhatsApp.

Authorizations

X-Tenant-IDstringRequired

Body

WhatsApp authentication request.

whatsapp_idstringRequired

profile_nameany ofOptional

stringOptional

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

post

/auth/whatsapp/v2/login

POST /auth/whatsapp/v2/login HTTP/1.1
Host: 
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-01-13T03:34:10.853Z",
        "updated_at": "2026-01-13T03:34:10.853Z",
        "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-01-13T03:34:10.853Z",
          "updated_at": "2026-01-13T03:34:10.853Z",
          "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-01-13T03:34:10.853Z",
          "updated_at": "2026-01-13T03:34:10.853Z",
          "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-01-13T03:34:10.853Z",
            "updated_at": "2026-01-13T03:34:10.853Z",
            "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-01-13T03:34:10.853Z",
                "updated_at": "2026-01-13T03:34:10.853Z",
                "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-01-13T03:34:10.853Z",
              "updated_at": "2026-01-13T03:34:10.853Z",
              "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-01-13T03:34:10.853Z",
              "updated_at": "2026-01-13T03:34:10.853Z",
              "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-01-13T03:34:10.853Z",
          "updated_at": "2026-01-13T03:34:10.853Z",
          "provider": {
            "id": "text",
            "name": "text",
            "icon": "text",
            "client_id": "text",
            "client_secret": "text",
            "created_at": "2026-01-13T03:34:10.853Z",
            "updated_at": "2026-01-13T03:34:10.853Z"
          },
          "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-01-13T03:34:10.853Z",
          "updated_at": "2026-01-13T03:34:10.853Z",
          "updated_by": "text"
        }
      }
    ],
    "is_active": true
  },
  "chatbots": [
    {
      "created_at": "2026-01-13T03:34:10.853Z",
      "updated_at": "2026-01-13T03:34:10.853Z",
      "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-01-13T03:34:10.853Z",
        "updated_at": "2026-01-13T03:34:10.853Z",
        "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-01-13T03:34:10.853Z",
        "updated_at": "2026-01-13T03:34:10.853Z",
        "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-01-13T03:34:10.853Z",
          "updated_at": "2026-01-13T03:34:10.853Z",
          "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-01-13T03:34:10.853Z",
              "updated_at": "2026-01-13T03:34:10.853Z",
              "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-01-13T03:34:10.853Z",
            "updated_at": "2026-01-13T03:34:10.853Z",
            "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-01-13T03:34:10.853Z",
            "updated_at": "2026-01-13T03:34:10.853Z",
            "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-01-13T03:34:10.853Z",
        "updated_at": "2026-01-13T03:34:10.853Z",
        "provider": {
          "id": "text",
          "name": "text",
          "icon": "text",
          "client_id": "text",
          "client_secret": "text",
          "created_at": "2026-01-13T03:34:10.853Z",
          "updated_at": "2026-01-13T03:34:10.853Z"
        },
        "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-01-13T03:34:10.853Z",
        "updated_at": "2026-01-13T03:34:10.853Z",
        "updated_by": "text"
      }
    }
  ],
  "organizations": [
    {
      "id": "text",
      "name": "text",
      "slug": "text",
      "team_id": "text",
      "encrypt_messages_enabled": true,
      "crypto_normalized_mode": "PLAINTEXT"
    }
  ],
  "account_type": "regular"
}

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

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

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

GET /auth/mobile/login?provider=text&redirect_uri=text HTTP/1.1
Host: 
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

nullOptional

stateany ofOptional

CSRF state parameter

stringOptional

nullOptional

errorany ofOptional

OAuth error if authentication failed

stringOptional

nullOptional

Responses

200

HTML page with mobile app redirect

text/html

Responsestring

400

Invalid or expired state parameter

422

Validation Error

application/json

500

OAuth processing failed

get

/auth/mobile/callback

GET /auth/mobile/callback HTTP/1.1
Host: 
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

X-Tenant-IDstringRequired

Body

Mobile token exchange request model.

exchange_codestring · min: 1 · max: 64Required

Exchange code received from OAuth callback

Responses

200

Complete authentication response

application/json

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

POST /auth/mobile/exchange HTTP/1.1
Host: 
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

OAuth2passwordRequired

Token URL:

__Secure-next-auth.session-tokenany ofOptional

stringOptional

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

/auth/me

GET /auth/me HTTP/1.1
Host: 
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
}

post

Direct API login.

Body

Direct API authentication request.

usernamestringRequired

passwordstringRequired

Responses

200

Successful Response

application/json

422

Validation Error

application/json

post

/auth/direct-api-login

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

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

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

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

OAuth2passwordRequired

Token URL:

Path parameters

typestring · enumRequired

Post auth login type

Possible values:

Responses

200

Successful Response

application/json

422

Validation Error

application/json

post

/auth/{type}/post-login

POST /auth/{type}/post-login HTTP/1.1
Host: 
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

OAuth2passwordRequired

Token URL:

__Secure-next-auth.session-tokenany ofOptional

stringOptional

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

/auth/initialize

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

{
  "ANY_ADDITIONAL_PROPERTY": true
}

Logout user

post

Logout user

Authorizations

OAuth2passwordRequired

Token URL:

Responses

200

Successfully logged out.

application/json

401

Token is required

application/json

post

/auth/logout

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

{
  "ANY_ADDITIONAL_PROPERTY": "text"
}

Resolve username

post

Resolve username

Authorizations

OAuth2passwordRequired

Token URL:

__Secure-next-auth.session-tokenany ofOptional

stringOptional

nullOptional

Body

Resolve username request.

identifierstringRequired

Responses

200

Successful Response

application/json

422

Validation Error

application/json

post

/auth/resolve-username

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

{
  "identifier": "text"
}

{
  "ANY_ADDITIONAL_PROPERTY": "text"
}

PreviousAPI Authentication Flow NextConversation

Last updated 1 month ago

hashtagWhatsapp Login

hashtagWhatsapp Register

hashtagWhatsapp Login V2

hashtagInitiate Mobile OAuth Login

hashtagHandle OAuth Callback

hashtagExchange Code for Tokens

hashtagGet Me

hashtagDirect API login

hashtagPost auth login

hashtagInitialize Stack Auth

hashtagLogout user

hashtagResolve username

Whatsapp Login

Whatsapp Register

Whatsapp Login V2

Initiate Mobile OAuth Login

Handle OAuth Callback

Exchange Code for Tokens

Get Me

Direct API login

Post auth login

Initialize Stack Auth

Logout user

Resolve username