> ## Documentation Index
> Fetch the complete documentation index at: https://compass.docs.sunnyscoach.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft OAuth Sign-in

> Exchange Microsoft OAuth authorization code for user profile and issue a session token. If the user does not exist, a new user is created.

Exchange Microsoft OAuth authorization code for user profile and issue a session token. If the user does not exist, a new user is created.

## Request

### Path Parameters

| Parameter | Type   | Required | Description                                           |
| --------- | ------ | -------- | ----------------------------------------------------- |
| code      | string | Yes      | Authorization code returned by Microsoft's OAuth flow |

## Response

### 200 OK - Successful sign-in

Returns user, token and profile picture.

```json theme={null}
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "_id": "64b7f1a2e4b0a5d3f9c12345",
    "emails": "user@example.com",
    "role": "user"
  },
  "profilePicture": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ..."
}
```

### 400 Bad Request

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid authorization code"
  }
}
```

### 500 Internal Server Error

```json theme={null}
{
  "error": {
    "code": "SERVER_ERROR",
    "message": "Internal server error"
  }
}
```

## Example

```bash theme={null}
curl -X GET 'http://localhost:2000/auth/signin/microsoft/M.R3_BAY.4a8b9c...'
```

## Notes

* The authorization code must be obtained from Microsoft's OAuth 2.0 flow
* If the user doesn't exist in the system, a new user account will be created
* The returned token should be stored securely and used for subsequent authenticated requests
* The profile picture may be returned as base64 data or a URL depending on implementation
* Token expiration time is typically 24 hours

## OAuth Flow

1. Redirect user to Microsoft's OAuth consent screen
2. User authorizes the application
3. Microsoft redirects back with authorization code
4. Exchange the code for access token and user profile using this endpoint


## OpenAPI

````yaml GET /auth/signin/microsoft/{code}
openapi: 3.0.3
info:
  title: COMPASS API
  version: 1.0.0
  description: OpenAPI specification for the Compass backend routes.
servers:
  - url: http://localhost:2000
    description: Local development server
security: []
tags:
  - name: Auth
    description: >-
      Authentication and session management endpoints (OAuth and session
      validation)
  - name: Users
    description: Operations for managing user records
  - name: Departments
    description: Operations for managing departments
  - name: Email Meter
    description: APIs to get Email Meter Stats
  - name: HubSpot Tickets
    description: Feedback APIs
  - name: Permissions
    description: Permissions APIs
  - name: Transcription
    description: Transcription APIs
paths:
  /auth/signin/microsoft/{code}:
    get:
      tags:
        - Auth
      summary: Sign in with Microsoft (OAuth code)
      description: >-
        Exchange Microsoft OAuth authorization code for user profile and issue a
        session token. If the user does not exist, a new user is created.
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
          description: Authorization code returned by Microsoft's OAuth flow
      responses:
        '200':
          description: Successful sign-in, returns user, token and profile picture
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                  user:
                    $ref: '#/components/schemas/UserMinimal'
                  profilePicture:
                    type: string
                    description: >-
                      Profile picture payload (may be base64 or URL depending on
                      implementation)
        '400':
          description: Validation error / bad request
        '500':
          description: Server error
components:
  schemas:
    UserMinimal:
      type: object
      properties:
        _id:
          type: string
        emails:
          type: string
          example: user@example.com
        role:
          type: string
          example: user

````