> For the complete documentation index, see [llms.txt](https://docs.scaleconnect.com.au/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scaleconnect.com.au/api/rest-api/scaleapp-rest-api/authentication.md).

# Authentication

User authentication and token management

## Get current authenticated user information

> Retrieves the authenticated user's profile and authentication details.\
>     \
> \*\*Business Logic:\*\*\
> \- Returns both database user info and Firebase auth info\
> \- Requires valid Bearer token authentication\
> \- User info includes profile data stored in the database\
> \- Auth info includes Firebase authentication details\
> \
> \*\*Use Cases:\*\*\
> \- Verifying user is authenticated\
> \- Getting user profile for display\
> \- Checking user permissions and roles\
> \- Debugging authentication issues\
> \
> \*\*For AI Agents:\*\*\
> \- Use this endpoint to verify authentication status\
> \- Returns comprehensive user information for context\
> \- Check emailVerified field to ensure email is confirmed\
> \- Use uid to correlate with Firebase auth records

```json
{"openapi":"3.0.0","info":{"title":"ScaleApp API","version":"1.0.0"},"tags":[{"name":"Authentication","description":"User authentication and token management"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"AuthMeResponseDto":{"type":"object","properties":{"user":{"description":"User database information","allOf":[{"$ref":"#/components/schemas/UserInfoDto"}]},"auth":{"description":"Firebase authentication information","allOf":[{"$ref":"#/components/schemas/UserAuthInfoDto"}]}},"required":["user","auth"]},"UserInfoDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique user identifier (UUID)"},"uid":{"type":"string","description":"Firebase authentication UID"},"name":{"type":"string","description":"User display name","nullable":true},"email":{"type":"string","description":"User email address","format":"email","nullable":true},"phoneNumber":{"type":"string","description":"Phone number in E.164 format","nullable":true},"createdAt":{"type":"string","description":"Timestamp when the user account was created","format":"date-time"},"updatedAt":{"type":"string","description":"Timestamp when the user account was last updated","format":"date-time"}},"required":["id","uid","name","email","phoneNumber","createdAt","updatedAt"]},"UserAuthInfoDto":{"type":"object","properties":{"uid":{"type":"string","description":"Firebase authentication UID"},"email":{"type":"string","description":"User email address","format":"email"},"phoneNumber":{"type":"string","description":"Phone number in E.164 format","nullable":true},"emailVerified":{"type":"boolean","description":"Whether the email has been verified"}},"required":["uid","email","phoneNumber","emailVerified"]}}},"paths":{"/v1/auth/me":{"get":{"description":"Retrieves the authenticated user's profile and authentication details.\n    \n**Business Logic:**\n- Returns both database user info and Firebase auth info\n- Requires valid Bearer token authentication\n- User info includes profile data stored in the database\n- Auth info includes Firebase authentication details\n\n**Use Cases:**\n- Verifying user is authenticated\n- Getting user profile for display\n- Checking user permissions and roles\n- Debugging authentication issues\n\n**For AI Agents:**\n- Use this endpoint to verify authentication status\n- Returns comprehensive user information for context\n- Check emailVerified field to ensure email is confirmed\n- Use uid to correlate with Firebase auth records","operationId":"AuthController_me_v1","parameters":[],"responses":{"200":{"description":"Successfully retrieved user information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthMeResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing Bearer token"}},"summary":"Get current authenticated user information","tags":["Authentication"]}}}}
```

## \[INTERNAL] Create custom Firebase authentication token

> Creates a Firebase custom token for a given UID.\
>     \
> \*\*⚠️ WARNING: This endpoint should NOT be enabled in production!\*\*\
> \
> \*\*Business Logic:\*\*\
> \- Generates a custom Firebase token for the specified UID\
> \- Token can be used to authenticate with Firebase\
> \- Intended for internal/testing purposes only\
> \
> \*\*Use Cases:\*\*\
> \- Testing authentication flows\
> \- Internal tools and scripts\
> \- Development and debugging\
> \
> \*\*For AI Agents:\*\*\
> \- DO NOT USE in production environments\
> \- This is an administrative endpoint\
> \- Requires internal system access\
> \- Use only for testing/development

```json
{"openapi":"3.0.0","info":{"title":"ScaleApp API","version":"1.0.0"},"tags":[{"name":"Authentication","description":"User authentication and token management"}],"paths":{"/v1/auth/custom-token":{"post":{"description":"Creates a Firebase custom token for a given UID.\n    \n**⚠️ WARNING: This endpoint should NOT be enabled in production!**\n\n**Business Logic:**\n- Generates a custom Firebase token for the specified UID\n- Token can be used to authenticate with Firebase\n- Intended for internal/testing purposes only\n\n**Use Cases:**\n- Testing authentication flows\n- Internal tools and scripts\n- Development and debugging\n\n**For AI Agents:**\n- DO NOT USE in production environments\n- This is an administrative endpoint\n- Requires internal system access\n- Use only for testing/development","operationId":"AuthController_createCustomToken_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomTokenRequestDto"}}}},"responses":{"201":{"description":"Custom token successfully generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomTokenResponseDto"}}}},"400":{"description":"Bad Request - Invalid UID provided"}},"summary":"[INTERNAL] Create custom Firebase authentication token","tags":["Authentication"]}}},"components":{"schemas":{"CustomTokenRequestDto":{"type":"object","properties":{"uid":{"type":"string","description":"Firebase user UID to generate custom token for"}},"required":["uid"]},"CustomTokenResponseDto":{"type":"object","properties":{"customToken":{"type":"string","description":"Firebase custom authentication token"}},"required":["customToken"]}}}}
```

## \[DEV ONLY] Get authentication token by phone number

> Retrieves an ID token for authentication using a phone number.\
>     \
> \*\*⚠️ WARNING: This is a DEVELOPMENT-ONLY endpoint and should NOT be deployed to production!\*\*\
> \
> \*\*Business Logic:\*\*\
> \- Looks up user by phone number\
> \- Generates a custom token\
> \- Exchanges custom token for ID token\
> \- Returns ID token that can be used for authentication\
> \
> \*\*Use Cases:\*\*\
> \- Development and testing\
> \- Automated testing scripts\
> \- Internal tooling\
> \- Debugging authentication issues\
> \
> \*\*For AI Agents:\*\*\
> \- ONLY use in development/testing environments\
> \- Never use in production\
> \- Phone number must be in E.164 format (+61412345678)\
> \- Returned idToken can be used as Bearer token

```json
{"openapi":"3.0.0","info":{"title":"ScaleApp API","version":"1.0.0"},"tags":[{"name":"Authentication","description":"User authentication and token management"}],"paths":{"/v1/auth/custom-token-by-phone":{"post":{"description":"Retrieves an ID token for authentication using a phone number.\n    \n**⚠️ WARNING: This is a DEVELOPMENT-ONLY endpoint and should NOT be deployed to production!**\n\n**Business Logic:**\n- Looks up user by phone number\n- Generates a custom token\n- Exchanges custom token for ID token\n- Returns ID token that can be used for authentication\n\n**Use Cases:**\n- Development and testing\n- Automated testing scripts\n- Internal tooling\n- Debugging authentication issues\n\n**For AI Agents:**\n- ONLY use in development/testing environments\n- Never use in production\n- Phone number must be in E.164 format (+61412345678)\n- Returned idToken can be used as Bearer token","operationId":"AuthController_getTokenByPhoneNumber_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneTokenRequestDto"}}}},"responses":{"201":{"description":"ID token successfully generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdTokenResponseDto"}}}},"400":{"description":"Bad Request - Invalid phone number format"},"404":{"description":"Not Found - No user found with that phone number"}},"summary":"[DEV ONLY] Get authentication token by phone number","tags":["Authentication"]}}},"components":{"schemas":{"PhoneTokenRequestDto":{"type":"object","properties":{"phoneNumber":{"type":"string","description":"Phone number in E.164 format (e.g., +61412345678)","pattern":"^\\+[1-9]\\d{1,14}$"}},"required":["phoneNumber"]},"IdTokenResponseDto":{"type":"object","properties":{"idToken":{"type":"string","description":"Firebase ID token that can be used for authentication"}},"required":["idToken"]}}}}
```

## Retrieve authenticated broker details

> \
>     Returns the currently authenticated broker’s profile along with authentication metadata.\
>       \
>     \*\*Business Logic\*\*\
>     \- Validates the Bearer token\
>     \- Fetches broker profile data from the database\
>     \- Fetches authentication details from Supabase\
>     \- If the broker profile does not exist, it is automatically created using Supabase data\
>       \
>     \*\*Use Cases\*\*\
>     \- Verify broker authentication state\
>     \- Load broker profile after login or signup\
>     \- Ensure broker profile integrity and consistency\
>     

```json
{"openapi":"3.0.0","info":{"title":"ScaleApp API","version":"1.0.0"},"tags":[{"name":"Authentication","description":"User authentication and token management"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"BrokerAuthMeResponseDto":{"type":"object","properties":{"user":{"description":"User database information","allOf":[{"$ref":"#/components/schemas/UserInfoDto"}]},"auth":{"description":"Firebase authentication information","allOf":[{"$ref":"#/components/schemas/UserAuthInfoDto"}]},"profile":{"description":"Broker profile summary","nullable":true,"allOf":[{"$ref":"#/components/schemas/BrokerProfileSummaryDto"}]},"accountInfo":{"description":"Broker account info summary","nullable":true,"allOf":[{"$ref":"#/components/schemas/AccountInfoSummaryDto"}]},"schedulingSettings":{"description":"Scheduling bot settings summary","nullable":true,"allOf":[{"$ref":"#/components/schemas/SchedulingSettingsSummaryDto"}]},"team":{"description":"Broker team summary","nullable":true,"allOf":[{"$ref":"#/components/schemas/TeamSummaryDto"}]}},"required":["user","auth"]},"UserInfoDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique user identifier (UUID)"},"uid":{"type":"string","description":"Firebase authentication UID"},"name":{"type":"string","description":"User display name","nullable":true},"email":{"type":"string","description":"User email address","format":"email","nullable":true},"phoneNumber":{"type":"string","description":"Phone number in E.164 format","nullable":true},"createdAt":{"type":"string","description":"Timestamp when the user account was created","format":"date-time"},"updatedAt":{"type":"string","description":"Timestamp when the user account was last updated","format":"date-time"}},"required":["id","uid","name","email","phoneNumber","createdAt","updatedAt"]},"UserAuthInfoDto":{"type":"object","properties":{"uid":{"type":"string","description":"Firebase authentication UID"},"email":{"type":"string","description":"User email address","format":"email"},"phoneNumber":{"type":"string","description":"Phone number in E.164 format","nullable":true},"emailVerified":{"type":"boolean","description":"Whether the email has been verified"}},"required":["uid","email","phoneNumber","emailVerified"]},"BrokerProfileSummaryDto":{"type":"object","properties":{"id":{"type":"number"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string"},"phone_number":{"type":"string"}},"required":["id","first_name","last_name","email","phone_number"]},"AccountInfoSummaryDto":{"type":"object","properties":{"account_type":{"type":"string"},"trading_name":{"type":"string"},"aggregator":{"type":"string"},"number_of_clients":{"type":"number"}},"required":["account_type","trading_name","aggregator","number_of_clients"]},"SchedulingSettingsSummaryDto":{"type":"object","properties":{"clientReadinessAction":{"type":"string"},"leadTimeMonths":{"type":"number"},"meetingTrigger":{"type":"string"},"reviewFrequency":{"type":"string"}},"required":["clientReadinessAction","leadTimeMonths","meetingTrigger","reviewFrequency"]},"TeamSummaryDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"members":{"type":"array","items":{"$ref":"#/components/schemas/TeamMemberSummaryDto"}}},"required":["id","name","members"]},"TeamMemberSummaryDto":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"joinedAt":{"format":"date-time","type":"string"},"user":{"type":"object"}},"required":["id","role","joinedAt","user"]}}},"paths":{"/v1/auth/broker/me":{"get":{"description":"\n    Returns the currently authenticated broker’s profile along with authentication metadata.\n      \n    **Business Logic**\n    - Validates the Bearer token\n    - Fetches broker profile data from the database\n    - Fetches authentication details from Supabase\n    - If the broker profile does not exist, it is automatically created using Supabase data\n      \n    **Use Cases**\n    - Verify broker authentication state\n    - Load broker profile after login or signup\n    - Ensure broker profile integrity and consistency\n    ","operationId":"AuthController_brokerMe_v1","parameters":[],"responses":{"200":{"description":"Successfully retrieved broker information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrokerAuthMeResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing Bearer token"}},"summary":"Retrieve authenticated broker details","tags":["Authentication"]}}}}
```

## Delete the authenticated broker's account data

> \
>     Deletes the broker's own records from the database. Called by ScaleConnect\
>     before it deletes the Supabase auth user, so no data is left pointing at an\
>     auth account that no longer exists.\
> \
>     Removes the user row and everything that cascades from it: broker profile,\
>     account info, teams they own, team memberships, notes, chats, notifications\
>     and personal financial records. Also removes the client links and import\
>     records keyed by their Supabase id, which have no foreign key and would\
>     otherwise be left behind.\
> \
>     When an admin calls this with \`?impersonateBrokerId=\`, the guard has already\
>     swapped the request identity to that broker, so this deletes the impersonated\
>     broker's account and never the admin's own.\
>     

```json
{"openapi":"3.0.0","info":{"title":"ScaleApp API","version":"1.0.0"},"tags":[{"name":"Authentication","description":"User authentication and token management"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}}},"paths":{"/v1/auth/broker/account":{"delete":{"description":"\n    Deletes the broker's own records from the database. Called by ScaleConnect\n    before it deletes the Supabase auth user, so no data is left pointing at an\n    auth account that no longer exists.\n\n    Removes the user row and everything that cascades from it: broker profile,\n    account info, teams they own, team memberships, notes, chats, notifications\n    and personal financial records. Also removes the client links and import\n    records keyed by their Supabase id, which have no foreign key and would\n    otherwise be left behind.\n\n    When an admin calls this with `?impersonateBrokerId=`, the guard has already\n    swapped the request identity to that broker, so this deletes the impersonated\n    broker's account and never the admin's own.\n    ","operationId":"AuthController_deleteBrokerAccount_v1","parameters":[],"responses":{"200":{"description":"Account data deleted"},"401":{"description":"Unauthorized"},"403":{"description":"Caller is not a Supabase broker"}},"summary":"Delete the authenticated broker's account data","tags":["Authentication"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.scaleconnect.com.au/api/rest-api/scaleapp-rest-api/authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.