Download OpenAPI specification:
Authentication and session management endpoints for the EncoraStream OTT Platform.
Covers:
Authenticate with email and password. Returns a JWT access token. Sets the refresh token as an HttpOnly cookie.
| email required | string <email> |
| password required | string <password> |
{- "email": "user@example.com",
- "password": "pa$$word"
}{- "data": {
- "access_token": "string",
- "token_type": "Bearer",
- "expires_in": 900
}
}Obtain a new access token using the refresh token stored in the HttpOnly cookie. Refresh tokens are single-use and rotated on every call. The previous refresh token is immediately invalidated. The new refresh token is set as an HttpOnly cookie in the response.
{- "data": {
- "access_token": "string",
- "token_type": "Bearer",
- "expires_in": 900
}
}Revokes the current access token and clears the refresh token cookie.
The session is immediately terminated server-side.
Clients must discard all stored tokens on receipt of 200.
{- "code": "RATE_LIMITED",
- "message": "Too many requests. Retry after the indicated period.",
- "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}Sends a password-reset link to the registered email address.
Security: Always returns 200 regardless of whether the email exists,
preventing account enumeration. The reset token is single-use,
expires in 15 minutes, and is invalidated on first use or on next login.
| email required | string <email> <= 254 characters |
{- "email": "user@example.com"
}{- "code": "VALIDATION_ERROR",
- "message": "One or more fields failed validation.",
- "errors": [
- {
- "field": "email",
- "message": "Must be a valid email address."
}, - {
- "field": "password",
- "message": "Must be at least 10 characters."
}
], - "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}Completes the reset using the token from the email link. All existing sessions are revoked on success.
| token required | string Opaque reset token from the emailed link. Never store or log. |
| new_password required | string <password> [ 10 .. 128 ] characters |
{- "token": "string",
- "new_password": "pa$$word_q"
}{- "access_token": "string",
- "token_type": "Bearer",
- "expires_in": 900
}Verifies the user's email using the token from the verification email.
Moves account from pending_verification to active.
| token required | string Opaque verification token from the emailed link. |
{- "token": "string"
}{- "data": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "email": "user@example.com",
- "email_verified": true,
- "display_name": "string",
- "phone": "string",
- "phone_verified": true,
- "locale": "en-US",
- "timezone": "America/New_York",
- "country_code": "US",
- "preferred_language": "en",
- "status": "active",
- "roles": [
- "subscriber"
], - "mfa_enabled": false,
- "terms_accepted_at": "2019-08-24T14:15:22Z",
- "last_login_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
}Resends the verification email. Rate-limited to 3 requests per hour per account.
Always returns 200 to prevent email enumeration.
| email required | string <email> <= 254 characters |
{- "email": "user@example.com"
}{- "code": "RATE_LIMITED",
- "message": "Too many requests. Retry after the indicated period.",
- "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}Creates a new user account. Sends an email-verification message. Rate-limited strictly to prevent account enumeration: identical error responses are returned for existing and new email addresses.
| email required | string <email> <= 254 characters |
| password required | string <password> [ 10 .. 128 ] characters Must contain uppercase, lowercase, digit, and special character. |
| display_name | string <= 100 characters |
| phone | string <= 20 characters ^\+[1-9]\d{1,14}$ |
| locale | string BCP-47 language tag. Defaults to Accept-Language header if omitted. |
| country_code | string = 2 characters ISO 3166-1 alpha-2. Used for tax calculation and geo-gating. |
| accept_terms required | boolean Value: true Must be true — user confirms acceptance of Terms of Service and Privacy Policy. Stored with timestamp for audit. |
{- "email": "user@example.com",
- "password": "pa$$word_q",
- "display_name": "string",
- "phone": "string",
- "locale": "en-US",
- "country_code": "US",
- "accept_terms": true
}{- "data": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "email": "user@example.com",
- "email_verified": true,
- "display_name": "string",
- "phone": "string",
- "phone_verified": true,
- "locale": "en-US",
- "timezone": "America/New_York",
- "country_code": "US",
- "preferred_language": "en",
- "status": "active",
- "roles": [
- "subscriber"
], - "mfa_enabled": false,
- "terms_accepted_at": "2019-08-24T14:15:22Z",
- "last_login_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
}Returns all active login sessions for the current account.
{- "data": [
- {
- "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
- "device_type": "smart_tv",
- "platform": "string",
- "ip_address_hint": "string",
- "is_current": true,
- "created_at": "2019-08-24T14:15:22Z",
- "last_active_at": "2019-08-24T14:15:22Z"
}
]
}Terminates a single session. Use current as the session_id to revoke the active session (logout).
| session_id required | string |
{- "code": "UNAUTHORIZED",
- "message": "Access token is missing or invalid.",
- "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}Verifies a TOTP code. Used to:
/me/auth/mfa/setup.| totp_code required | string [ 6 .. 8 ] characters ^\d+$ |
{- "totp_code": "string"
}{- "step_up_token": "string",
- "expires_in": 300
}Removes MFA from the account. Requires a valid TOTP code for confirmation. All sessions are revoked.
| totp_code required | string [ 6 .. 8 ] characters ^\d+$ |
{- "totp_code": "string"
}{- "code": "NOT_FOUND",
- "message": "Resource not found.",
- "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
}Returns one-time backup codes for MFA recovery. Codes are hashed server-side and shown only once — the full plaintext codes are displayed on first generation or after regeneration. Requires a valid step-up token.
{- "codes": [
- "string"
], - "generated_at": "2019-08-24T14:15:22Z"
}Invalidates all existing recovery codes and issues a new set. Requires TOTP confirmation.
| totp_code required | string [ 6 .. 8 ] characters ^\d+$ |
{- "totp_code": "string"
}{- "codes": [
- "string"
], - "generated_at": "2019-08-24T14:15:22Z"
}