# Getting Started with Authentication

## Tokens Overview

### Authentication App Access Token (JWT)
- **Use for:** Calling protected Authentication endpoints.  
- **Header:** `Authorization: Bearer <current_auth_access_token>`  
- **Default validity:** 7 days  

### Ejento Access Token
- **Use for:** Ejento Platform APIs (besides Authentication endpoints).  
- **Header:** Typically `Authorization: Bearer <ejento_access_token>`  
- **Default validity:** 7 days  

> ⚠️ These tokens serve different purposes and are **not interchangeable**.

---

## When to Use Which Endpoint

### 1. Login with Email/Password
- **Endpoint:** `POST /auth-service/api/v2/login/access-token`  
- **Body (x-www-form-urlencoded):**  
  - `username`  
  - `password`  
- **Returns:** Both tokens (Authentication App access token and Ejento access token)  
- **Use when:** The user has a password  

---

### 2. Passwordless (Email-based Code → Exchange)

#### Step 1: Request Token
- **Endpoint:** `POST /auth-service/api/v2/login/passwordless/request-token`  
- **Body (JSON):**
  ```json
  { "email": "user@example.com" }
  ```
- Sends a single-use exchange code to the user's email (expires in 10 minutes)

#### Step 2: Exchange Code for Tokens
- **Endpoint:** `POST /auth-service/api/v2/login/passwordless/exchange-tokens`  
- **Body (JSON):**
  ```json
  { "code": "<opaque-exchange-code-from-email>" }
  ```
- **Returns:** Both tokens  
- **Use when:** The user does not use a password to sign in  

---

### 3. Sign Up
- **Endpoint:** `POST /auth-service/api/v2/users/signup`  
- **Body (JSON):**
  ```json
  {
    "email": "user@example.com",
    "full_name": "User Name",
    "password": "password123"
  }
  ```
- **Returns:** The created user  
- On first login, you'll obtain both tokens  

---

### 4. Refresh Authentication App Access Token
- **Endpoint:** `POST /auth-service/api/v2/users/refresh-access-token`  
- **Header:** `Authorization: Bearer <current_auth_access_token>`  
- **Returns:** Refreshed Authentication App Access Token and Ejento Access Token 

---

### 5. Update Own Password
- **Endpoint:** `PATCH /auth-service/api/v2/users/me/password`  
- **Header:** `Authorization: Bearer <current_auth_access_token>`  
- **Body (JSON):**
  ```json
  {
    "current_password": "old_password",
    "new_password": "new_password123"
  }
  ```

---

### 6. Azure AD Token Login
- **Endpoint:** `POST /auth-service/api/v2/sso/microsoft/azure-token-login`  
- **Body (JSON):**
  ```json
  {
    "email": "user@yourcompany.com",
    "azure_ad_token": "<Azure AD id_token>",
    "full_name": "User Name",      // optional
    "auto_create": true,           // optional, default true
    "organization_id": 1          // optional
  }
  ```
- **Returns:** access-token and ejento-access-token token  
- **Use when:** The user is already authenticated via Microsoft (Azure AD / MSAL) and you want to exchange their Azure AD token for Ejento tokens without a browser redirect  
- **Authorization:** Not required — the Azure AD token is the credential  

#### **Note**: Review this [Guide](https://api.ejento.ai/guides/authentication-with-azure-ad-token) for detailed overview of Azure AD Token Login.

---

## Typical Flows

### Password-Based Authentication Flow
1. Call `/auth-service/api/v2/login/access-token`  
2. Store both tokens  
3. Use:
   - Authentication App access token → for Authentication APIs  
   - Ejento access token → for Ejento Platform APIs  

```mermaid
graph TD
    A[User enters credentials in POST /auth-service/api/v2/login/access-token]
    A --> B[Receive both tokens]
    B --> C[Store tokens securely]
    C --> D[Use auth token for auth APIs]
    C --> E[Use ejento token for platform APIs]
    D --> F[Refresh tokens before expiry]
```


### Passwordless Authentication Flow
1. Call `/auth-service/api/v2/login/passwordless/request-token`  
2. Retrieve the email code  
3. Call `/api/v2/login/passwordless/exchange-tokens` with the code  
4. Store both tokens and use as above  

```mermaid
graph TD
    A[User enters email in POST /auth-service/api/v2/login/passwordless/request-token]
    A --> B[Email sent with code]
    B --> C[User submits code in POST /login/passwordless/exchange-tokens]
    C --> D[Receive both tokens]
    D --> E[Store tokens securely]
    E --> F[Use auth token for auth APIs]
    E --> G[Use ejento token for platform APIs]
    F --> H[Refresh tokens before expiry]
```

### Azure AD Token Login Flow
1. Obtain an Azure AD `id_token` for the user via MSAL  
2. Call `/auth-service/api/v2/sso/microsoft/azure-token-login` with the token and email  
3. Store both tokens and use as above  

```mermaid
graph TD
    A[App obtains Azure AD id_token via MSAL]
    A --> B[POST /auth-service/api/v2/sso/microsoft/azure-token-login]
    B --> C[Receive both tokens]
    C --> D[Store tokens securely]
    D --> E[Use access_token for auth APIs]
    D --> F[Use ejento_access_token for platform APIs]
    E --> G[Refresh tokens before expiry]
```

### Keeping Sessions Fresh
- Before the Authentication App access token expires (7 days), call `/auth-service/api/v2/users/refresh-access-token` to get refreshed tokens (Ejento Access Token and Authentication App Access Token).

---

## Notes
- The email exchange code is **single-use** and **expires in 10 minutes**.  
- It is **not** a token itself — you must exchange it to receive both tokens.  
- **Never** send tokens in URLs.  
- Always include tokens in the `Authorization` header when calling APIs.