Authentication

All Scriptix API requests require authentication using Bearer tokens in the Authorization header.

Base URL

https://api.scriptix.io

All endpoints use the /api/v3 prefix unless otherwise specified.

Authentication Methods

Scriptix supports two authentication methods:

JWT Session Tokens - User login sessions with optional MFA
API Access Tokens - Long-lived tokens for programmatic access

User Authentication

Endpoint: POST /api/v3/auth/login?login_type=token

Request Format:

Content-Type: application/x-www-form-urlencoded
Credentials included: true

Request Body:

username=user@example.com
password=yourpassword
remember_me=true

Success Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "login": true,
  "mfa_required": false,
  "session_id": "abc123",
  "signature": "xyz789"
}

Response Fields:

access_token (string, optional) - JWT token for authentication
login (boolean) - Login success status
mfa_required (boolean) - Whether MFA verification is required
session_id (string, optional) - Session identifier
signature (string, optional) - Session signature

Token Storage: The JWT token is stored in cookies with the following settings:

Cookie name: act
Expiration: 7 days
Secure: true
SameSite: Strict

Remember Me: When remember_me=true, the session is kept active for longer between logins.

Multi-Factor Authentication (MFA)

If the login response returns "mfa_required": true, complete authentication with the MFA endpoint.

Endpoint: POST /api/v3/auth/login/mfa?login_type=token

Request Format:

Content-Type: application/x-www-form-urlencoded

Request Body:

username=user@example.com
password=yourpassword
remember_me=true
totp_code=123456
backup_code=123456

Fields:

username (required) - User email address
password (required) - User password
remember_me (optional) - Remember login preference
totp_code (required) - Time-based one-time password from authenticator app
backup_code (required) - Backup recovery code

Note: Both totp_code and backup_code are sent with the same value. The server determines which type to validate.

Success Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "login": true,
  "mfa_required": false,
  "session_id": "abc123",
  "signature": "xyz789"
}

Microsoft SSO

Endpoint: GET /api/v3/auth/login/microsoft?redirect_uri={redirectUri}

Query Parameters:

redirect_uri (required) - URL to redirect to after authentication

The user is redirected to Microsoft for authentication, then returned to the specified redirect URI with the token.

Logout

Endpoint: POST /api/v3/auth/logout

Headers:

Authorization: Bearer {token}

Behavior:

Invalidates the current session
Removes the authentication token from cookies

API Access Tokens

API tokens are long-lived credentials for programmatic access to the API.

List API Tokens

Endpoint: GET /api/v3/tokens

Headers:

Authorization: Bearer {token}

Query Parameters:

offset (integer, default: 0) - Number of items to skip
limit (integer, default: 25) - Number of items to return
q (string, optional) - Search query
sort (string, optional) - Field to sort by
direction (string, optional) - Sort direction: asc or desc

Response Format:

{
  "result": {
    "result": {
      "id": 123,
      "name": "Production API Token",
      "key": "token_prefix_here",
      "token_value": "full_token_value",
      "type": "batch",
      "expires": "2026-01-17T10:00:00Z"
    },
    "count": 1,
    "total_results": 5
  }
}

Token Object Fields:

id (number) - Token identifier
name (string) - Token name
key (string) - Token key/prefix
token_value (string) - Full token value
type (string) - Token type: batch or realtime
expires (string) - Expiration timestamp (ISO 8601)

Create API Token

Endpoint: POST /api/v3/tokens

Headers:

Authorization: Bearer {token}
Content-Type: application/json

Request Body:

{
  "name": "Production API Token",
  "type": "batch",
  "years_valid": 1
}

Request Fields:

name (string, required) - Token name
type (string, required) - Token type: batch or realtime
years_valid (number, required) - Token validity period in years (1, 2, or 5)

Token Types:

batch - Store data then process it (standard API usage)
realtime - Process data as it comes (real-time streaming)

Response: Returns the created token object with the full token_value.

⚠️ Important: The full token value is only returned once during creation. Store it securely immediately.

Delete API Token

Endpoint: DELETE /api/v3/tokens/{tokenId}

Headers:

Authorization: Bearer {token}

Path Parameters:

tokenId (string, required) - Token ID to delete

Response: Returns success status on deletion.

Two-Factor Authentication Management

Get QR Code

Endpoint: GET /api/v3/mfa/2fa/qr_code

Headers:

Authorization: Bearer {token}

Response: Returns QR code data for setting up authenticator app.

Get Backup Codes

Endpoint: GET /api/v3/mfa/2fa/backup_codes

Headers:

Authorization: Bearer {token}

Response: Returns backup recovery codes for account access.

Enable 2FA

Endpoint: POST /api/v3/mfa/2fa/enable?totp_code={code}

Headers:

Authorization: Bearer {token}

Query Parameters:

totp_code (required) - TOTP code from authenticator app

Disable 2FA

Endpoint: POST /api/v3/mfa/2fa/disable?token={token}&backup_code={code}

Headers:

Authorization: Bearer {token}

Query Parameters:

token (required) - Authentication token
backup_code (required) - Backup recovery code

Verify TOTP Code

Endpoint: POST /api/v3/mfa/2fa/verify_totp

Headers:

Authorization: Bearer {token}

Verify Backup Code

Endpoint: POST /api/v3/mfa/2fa/verify_backup_code

Headers:

Authorization: Bearer {token}

Using Bearer Tokens

All authenticated API requests must include the token in the Authorization header:

Authorization: Bearer YOUR_TOKEN_HERE

Sending the Token

Include the token in the Authorization header on every request:

Authorization: Bearer YOUR_TOKEN_HERE

Handling 401 Responses

A 401 Unauthorized response means the token is missing, invalid, or expired. Re-authenticate to obtain a new token. Shared document pages use magic link authentication instead of Bearer tokens.

JWT Token Structure

JWT tokens contain the following decoded fields:

{
  "aud": ["audience"],
  "exp": 1234567890,        // Expiration timestamp
  "iat": 1234567890,        // Issued at timestamp
  "iss": "issuer",
  "nbf": 1234567890,        // Not before timestamp
  "uid": 123,               // User ID
  "oid": 456,               // Organization ID
  "scopes": ["CONTRIBUTOR"] // User roles/scopes
}

User Roles (scopes):

SYSOP - System operator
ORGADMIN - Organization administrator
RESELLER - Reseller account
CONTRIBUTOR - Content contributor
DEVELOPER - Developer access
CUSTOMER - Customer account
RESELLEE - Reseller's customer
TESTER - Testing access

Token Expiration

Tokens are validated on each request:

Expired tokens (based on exp field) are automatically removed
The application checks exp < Date.now() / 1000 to determine validity

Error Responses

401 Unauthorized

Triggers automatic logout (except on shared pages)

Common Causes:

Missing Authorization header
Invalid token
Expired token
Revoked token

422 Unprocessable Entity

Response Format:

{
  "error": "Validation error message"
}

This response contains an error field with the validation message.

Testing Authentication

Verify Current User

Endpoint: GET /api/v3/account/me

Headers:

Authorization: Bearer {token}

Response:

{
  "result": {
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "newsletter": false,
    "roles": [],
    "two_factor_active": false,
    "is_active": true,
    "id": 123,
    "identity_provider": "local"
  }
}

Use this endpoint to verify your token is valid and retrieve user information.

Rate Limiting

API requests are subject to rate limits based on your subscription plan. Rate limit information is not currently exposed in response headers.

Session Management

Inactivity Timeout

The application implements automatic logout after a period of inactivity. The timeout duration depends on the remember_me preference.

Shared Document Access

Shared documents (transcripts and captions) use magic link tokens instead of Bearer authentication. These pages do not trigger automatic logout on 401 errors.

Shared page patterns:

/transcripts/shared/*
/captions/shared/*

Base URL​

Authentication Methods​

User Authentication​

Standard Login​

Multi-Factor Authentication (MFA)​

Microsoft SSO​

Logout​

API Access Tokens​

List API Tokens​

Create API Token​

Delete API Token​

Two-Factor Authentication Management​

Get QR Code​

Get Backup Codes​

Enable 2FA​

Disable 2FA​

Verify TOTP Code​

Verify Backup Code​

Using Bearer Tokens​

Sending the Token​

Handling 401 Responses​

JWT Token Structure​

Token Expiration​

Error Responses​

401 Unauthorized​

422 Unprocessable Entity​

Testing Authentication​

Verify Current User​

Rate Limiting​

Session Management​

Inactivity Timeout​

Shared Document Access​

Base URL

Authentication Methods

User Authentication

Standard Login

Multi-Factor Authentication (MFA)

Microsoft SSO

Logout

API Access Tokens

List API Tokens

Create API Token

Delete API Token

Two-Factor Authentication Management

Get QR Code

Get Backup Codes

Enable 2FA

Disable 2FA

Verify TOTP Code

Verify Backup Code

Using Bearer Tokens

Sending the Token

Handling 401 Responses

JWT Token Structure

Token Expiration

Error Responses

401 Unauthorized

422 Unprocessable Entity

Testing Authentication

Verify Current User

Rate Limiting

Session Management

Inactivity Timeout

Shared Document Access