Auth

Registration, login, SSO, password management, and account deletion.

Complete Google sign-in

GET

/auth/sso/callback

Exchange a Google authorization code for EchoMode tokens. Call this with the code and state Google returned to your callback. Auto-registers the user and organization on first login.

Parameters

Query Parameters

code*

Type

string

Required

state*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"access_token": "string",

  

"expires_in": 0,

  

"is_new_user": false,

  

"needs_profile_completion": false,

  

"organization": {

  

  

"is_org_admin": true,

  

  

"name": "string",

  

  

"org_id": "string",

  

  

"tier": "string"

  

},

  

"refresh_token": "string",

  

"token_type": "bearer"

}

Samples

Delete account

DELETE

/v1/auth/account

Soft-delete the account, remove org/team membership, and invalidate all sessions. Password is required for users who have one; SSO-only users may omit it.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Request Body

application/json

Any of

Responses

Successful Response

Samples

Change password

POST

/v1/auth/change-password

Verify current password, set a new one, and invalidate all refresh tokens.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Request Body

application/json

Responses

Successful Response

Samples

Log in

POST

/v1/auth/login

Email and password; returns access and refresh tokens.

Request Body

application/json

Format"email"

Responses

Successful Response

Content-Type

application/json

{

  

"access_token": "string",

  

"expires_in": 0,

  

"is_new_user": false,

  

"needs_profile_completion": false,

  

"organization": {

  

  

"is_org_admin": true,

  

  

"name": "string",

  

  

"org_id": "string",

  

  

"tier": "string"

  

},

  

"refresh_token": "string",

  

"token_type": "bearer"

}

Samples

Log out

POST

/v1/auth/logout

Revoke the given refresh token server-side.

Request Body

application/json

Responses

Successful Response

Samples

Refresh tokens

POST

/v1/auth/refresh

Exchange a valid refresh token for new tokens (rotation may apply).

Request Body

application/json

Responses

Successful Response

Content-Type

application/json

{

  

"access_token": "string",

  

"expires_in": 0,

  

"is_new_user": false,

  

"needs_profile_completion": false,

  

"organization": {

  

  

"is_org_admin": true,

  

  

"name": "string",

  

  

"org_id": "string",

  

  

"tier": "string"

  

},

  

"refresh_token": "string",

  

"token_type": "bearer"

}

Samples

Register a new user

POST

/v1/auth/register

Create an account and a new organization for the user. To add users to an existing organization, org or team admins must use POST /entity/members.

Request Body

application/json

Any of

Format"email"

Any of

Any of

Any of

Any of

Responses

Successful Response

Content-Type

application/json

{

  

"access_token": "string",

  

"expires_in": 0,

  

"is_new_user": false,

  

"needs_profile_completion": false,

  

"organization": {

  

  

"is_org_admin": true,

  

  

"name": "string",

  

  

"org_id": "string",

  

  

"tier": "string"

  

},

  

"refresh_token": "string",

  

"token_type": "bearer"

}

Samples

Set initial password

POST

/v1/auth/set-password

Set a password on an SSO-only account so the user can sign in with email and password. Fails if a password is already configured.

Authorizations

HTTPBearer

Type

HTTP (bearer)

Request Body

application/json

Set a password on an SSO-only account (no existing password_hash).

Responses

Successful Response

Samples

Start Google sign-in

POST

/v1/auth/sso/authorize

Generate a Google OAuth authorization URL. EchoMode uses direct Google OAuth; callers redirect the user's browser to the returned URL.

Pass redirect_uri to receive Google's redirect at your own callback; Google sends the browser there with code and state, which you then hand to GET /auth/sso/callback to exchange for tokens. Omit redirect_uri to use the configured default callback; omitting it returns 400 when the deployment has no default configured.

Request Body

application/json

Identity provider. Only Google sign-in is supported today.

Valid values"google""googleoauth"

Any of

Responses

Successful Response

Content-Type

application/json

{

  

"authorization_url": "string"

}

Samples