# Authentication

## Authentication

TrainingArc uses **API keys** and **session tokens** to authorize access to its endpoints, depending on the context of the integration.

***

### 🔐 API Key Authentication

API keys are used for backend-to-backend or programmatic access, such as:

* Fetching a training module URL
* Accessing library sections
* Retrieving module metadata

#### 🔧 How to Authenticate

Include the API key in the `Authorization` header as a **Bearer token**:

```http
Authorization: Bearer ta_org_5FLBfdCUBOVOniy7cmUlVzn1Eda2fcnVtdUG91XG
```

#### ✅ Example Use Case

```http
GET /organizations/org123/library/modules/mod789
Authorization: Bearer ta_org_abc123
```

> This will return a signed module URL and associated cookies scoped to the module.

***

### 📦 Module URL Authentication (Signed Cookies)

When a valid API key is used to request a module, the TrainingArc API returns:

* A **signed CloudFront URL** pointing to the training module
* A set of **signed cookies** scoped to that module’s path

These cookies grant **temporary access** to the static assets (HTML, JS, CSS) of the module hosted on **CloudFront**.

#### 🧾 Example Response from `GET /library/modules/:moduleId`

```json
jsonCopyEdit{
  "success": true,
  "message": "Library Module retrieved successfully.",
  "data": {
    "url": "https://training-assets.example.com/mod789/index.html",
    "signedCookies": {
      "CloudFront-Key-Pair-Id": "APKA12345EXAMPLE",
      "CloudFront-Signature": "Zkljhasd89q...",
      "CloudFront-Policy": "eyJleHBpcmVzIjox..."
    }
  }
}
```

#### ⚙️ How It Works

* The `url` is time-limited and scoped to the module.
* The cookies are also scoped to the **module folder path** (e.g., `/mod789/*`) to prevent access to other modules.
* These cookies must be attached in the browser before attempting to load the iframe or page.

> If you're embedding a module in an `<iframe>`, you must ensure that the signed cookies are present in the browser **before** loading the iframe.

***

### 🧪 Session Token Authentication

Training modules (typically Articulate Rise 360 content) submit xAPI learning data via session tokens.

#### Used For:

* Submitting xAPI statements to `/statements`

#### How It Works:

* The session token is passed in the `Authorization` header.
* It identifies the learner and their organization.

```http
PUT /statements?statementId=abc123
Authorization: Bearer ta_session_xyz789
Content-Type: application/json
```

***

### 🔄 Token Validation

When a token is received by `/statements`, TrainingArc:

1. Verifies the token’s signature and expiration
2. Retrieves the learner and organization context
3. Forwards the xAPI statement to the organization’s webhook

***

### ⚠️ Common Errors

| Code | Message                       | Reason                                       |
| ---- | ----------------------------- | -------------------------------------------- |
| 401  | Unauthorized                  | Missing or invalid token                     |
| 403  | Invalid token                 | Token signed for another user/org            |
| 400  | Invalid xAPI statement format | Malformed request (usually in `/statements`) |

***

### ✅ Best Practices

* Never expose API keys in frontend code.
* Always fetch signed module URLs from a secure backend.
* Rotate API keys periodically.
* Store session tokens securely and use short expiration.
* Attach signed cookies in the browser before rendering training content.
* Consider setting cookies with `SameSite=None; Secure; Path=/mod789/` if managing cross-origin iframe loading.
