Documentation

Auth Routes

These pages document the live auth endpoints mounted under /api/auth.

Endpoints

`GET /api/auth/accounts`

Protected account listing for the current authenticated session.

Request
GET /api/auth/accounts
Authorization: Bearer <access-token>

Response 200
{
  "accounts": [
    {
      "id": "uuid",
      "orgId": "uuid",
      "username": "owner_user",
      "email": "[email protected]",
      "authProvider": "cognito",
      "cognitoSub": "sub-123",
      "roleId": "uuid"
    }
  ]
}

`GET /api/auth/permissions`

Protected canonical list of backend permission keys with stable integer ids.

Request
GET /api/auth/permissions
Authorization: Bearer <access-token>

Response 200
{
  "permissions": [
    {
      "id": 1,
      "key": "auth:delete"
    },
    {
      "id": 2,
      "key": "auth:delete_self"
    }
  ],
  "permissionMap": {
    "auth:delete": 1,
    "auth:delete_self": 2
  }
}

`GET /api/auth/cognito`

Returns backend Cognito configuration status for the direct client auth flow.

Request
GET /api/auth/cognito

Response 200
{
  "provider": "cognito",
  "configured": true,
  "message": "Cognito is configured for client-side login with backend JWT verification."
}

`POST /api/auth/cognito/refresh`

Refreshes Cognito access and ID tokens using a refresh token.

Request
POST /api/auth/cognito/refresh
Content-Type: application/json

{
  "refreshToken": "<cognito-refresh-token>"
}

Response 200
{
  "provider": "cognito",
  "accessToken": "...",
  "idToken": "...",
  "refreshToken": "...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

`POST /api/auth/cognito/verify`

Verifies a Cognito access token without provisioning local account state.

Request
POST /api/auth/cognito/verify
Content-Type: application/json

{
  "accessToken": "<cognito-access-token>"
}

Response 200
{
  "provider": "cognito",
  "verified": true,
  "account": null,
  "claims": {
    "sub": "sub-123",
    "tokenUse": "access",
    "username": "silver1713"
  }
}

`POST /api/auth/cognito/resolve`

Verifies Cognito tokens and resolves or provisions the local backend account session.

Request
POST /api/auth/cognito/resolve
Content-Type: application/json

{
  "accessToken": "<cognito-access-token>",
  "idToken": "<cognito-id-token>"
}

Response 200
{
  "provider": "cognito",
  "verified": true,
  "provisioned": true,
  "account": {
    "id": "uuid",
    "orgId": "uuid",
    "username": "silver1713",
    "email": "[email protected]",
    "authProvider": "cognito",
    "cognitoSub": "sub-123",
    "roleId": "uuid"
  },
  "claims": {
    "sub": "sub-123",
    "tokenUse": "access",
    "username": "silver1713"
  }
}

`POST /api/auth/cognito/login`

Deprecated compatibility endpoint for backend-mediated Cognito login.

Request
POST /api/auth/cognito/login
Content-Type: application/json

{
  "username": "silver1713",
  "password": "example-password"
}

Response 200
{
  "provider": "cognito",
  "account": null,
  "accessToken": "...",
  "idToken": "...",
  "refreshToken": "..."
}

`POST /api/auth/cognito/register`

Deprecated compatibility endpoint for backend-mediated Cognito registration.

Request
POST /api/auth/cognito/register
Content-Type: application/json

{
  "email": "[email protected]",
  "username": "silver1713",
  "password": "example-password",
  "orgId": "uuid",
  "roleId": "uuid"
}

Response 201
{
  "provider": "cognito",
  "account": {
    "id": "uuid",
    "orgId": "uuid",
    "username": "silver1713",
    "email": "[email protected]",
    "authProvider": "cognito",
    "cognitoSub": "sub-123",
    "roleId": "uuid"
  },
  "userSub": "sub-123",
  "userConfirmed": false
}

`POST /api/auth/backend/login`

Deprecated local backend login flow.

Request
POST /api/auth/backend/login
Content-Type: application/json

{
  "username": "local_user",
  "password": "example-password"
}

Response 200
{
  "accessToken": "...",
  "account": {
    "id": "uuid",
    "orgId": "uuid",
    "username": "local_user",
    "email": "[email protected]",
    "authProvider": "backend",
    "cognitoSub": null,
    "roleId": "uuid"
  }
}

`POST /api/auth/backend/register`

Deprecated local backend registration flow.

Request
POST /api/auth/backend/register
Content-Type: application/json

{
  "email": "[email protected]",
  "username": "local_user",
  "password": "example-password",
  "orgId": "uuid",
  "roleId": "uuid"
}

Response 201
{
  "account": {
    "id": "uuid",
    "orgId": "uuid",
    "username": "local_user",
    "email": "[email protected]",
    "authProvider": "backend",
    "cognitoSub": null,
    "roleId": "uuid"
  }
}

`POST /api/auth/login`

Deprecated alias for /api/auth/backend/login.

Request
POST /api/auth/login
Content-Type: application/json

{
  "username": "local_user",
  "password": "example-password"
}

Response 200
{
  "accessToken": "...",
  "account": {
    "id": "uuid",
    "orgId": "uuid",
    "username": "local_user",
    "email": "[email protected]",
    "authProvider": "backend",
    "cognitoSub": null,
    "roleId": "uuid"
  }
}