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:

Authorization: Bearer ta_org_5FLBfdCUBOVOniy7cmUlVzn1Eda2fcnVtdUG91XG

✅ Example Use Case

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

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.

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.

PreviousIntroductionNextFAQ

Last updated