Skip to main content

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:

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

User Authentication​

Standard Login​

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 preference is stored in localStorage as scriptix_remember_me.

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
  • Clears scriptix_remember_me from localStorage

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

Automatic Token Injection​

The application automatically injects the Bearer token into all requests via an Axios request interceptor:

request.headers.set('Authorization', `Bearer ${token}`);

Automatic Logout on 401​

The application automatically logs out users when receiving a 401 Unauthorized response, except on shared document pages (which 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 is automatically converted to a Yup ValidationError by the Axios response interceptor.

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/*