API docs by Redocly

EncoraStream Auth API (2.0.0)

Download OpenAPI specification:

EncoraStream API Team: api-support@encorastream.com License: Proprietary

Authentication and session management endpoints for the EncoraStream OTT Platform.

Covers:

  • OAuth 2.0 PKCE authorization code flow
  • Token issuance, refresh, and revocation
  • Device authorization grant
  • Social login
  • Password reset and email verification
  • OIDC discovery
  • User registration
  • Session management and MFA

OIDC

OpenID Connect discovery

Auth

OAuth 2.0 token flows, revocation, password reset, email verification

OpenID Connect Discovery Document

Returns the OIDC provider metadata (RFC 8414). Used by OIDC clients to auto-discover endpoints.

Responses

Response samples

Content type
application/json
{ }

Initiate OAuth 2.0 PKCE Authorization

Redirects the user-agent to the authorization server.

PKCE Requirements (RFC 7636)

  1. Generate a cryptographically random code_verifier (43–128 chars, URL-safe base64).
  2. Compute code_challenge = BASE64URL(SHA256(code_verifier)).
  3. Use code_challenge_method=S256 — plain is not accepted.

Abuse Protection

  • state must be a cryptographically random value (≥16 bytes) stored in the client session.
  • Validate state on redirect to prevent CSRF.
query Parameters
response_type
required
string
Value: "code"
client_id
required
string
redirect_uri
required
string <uri>
scope
required
string
Example: scope=openid profile content:read subscription:read watchlist devices drm
state
required
string
code_challenge
required
string
code_challenge_method
required
string
Value: "S256"

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "Request body is malformed JSON.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Exchange Authorization Code for Tokens (PKCE)

Exchange the authorization code for access, refresh, and ID tokens. Supply code_verifier matching the code_challenge sent in /auth/authorize.

Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string
Value: "authorization_code"
code
required
string

Authorization code from redirect.

redirect_uri
required
string <uri>
client_id
required
string
code_verifier
required
string [ 43 .. 128 ] characters

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 900,
  • "refresh_token": "string",
  • "scope": "openid profile content:read subscription:read watchlist devices drm",
  • "id_token": "string"
}

Refresh Access Token

Obtain a new access token using a refresh token. Refresh tokens are single-use and rotated on every call. The previous refresh token is immediately invalidated.

Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string
Value: "refresh_token"
refresh_token
required
string
client_id
required
string

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 900,
  • "refresh_token": "string",
  • "scope": "openid profile content:read subscription:read watchlist devices drm",
  • "id_token": "string"
}

Revoke Token (Logout)

Revoke an access or refresh token (RFC 7009). The session is immediately terminated server-side. Clients must discard all stored tokens on receipt of 200.

Authorizations:
BearerAuth
Request Body schema: application/x-www-form-urlencoded
required
token
required
string
token_type_hint
string
Enum: "access_token" "refresh_token"
client_id
required
string

Responses

Response samples

Content type
application/json
{
  • "code": "RATE_LIMITED",
  • "message": "Too many requests. Retry after the indicated period.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Request Password Reset Email

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.

Request Body schema: application/json
required
email
required
string <email> <= 254 characters

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "code": "VALIDATION_ERROR",
  • "message": "One or more fields failed validation.",
  • "errors": [
    ],
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Confirm Password Reset

Completes the reset using the token from the email link. All existing sessions are revoked on success.

Request Body schema: application/json
required
token
required
string

Opaque reset token from the emailed link. Never store or log.

new_password
required
string <password> [ 10 .. 128 ] characters

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "new_password": "pa$$word_q"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 900,
  • "refresh_token": "string",
  • "scope": "openid profile content:read subscription:read watchlist devices drm",
  • "id_token": "string"
}

Verify Email Address

Verifies the user's email using the token from the verification email. Moves account from pending_verification to active.

Request Body schema: application/json
required
token
required
string

Opaque verification token from the emailed link.

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "email_verified": true,
  • "display_name": "string",
  • "phone": "string",
  • "phone_verified": true,
  • "avatar_url": "http://example.com",
  • "locale": "en-US",
  • "timezone": "America/New_York",
  • "country_code": "US",
  • "preferred_language": "en",
  • "status": "active",
  • "roles": [
    ],
  • "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"
}

Resend Email Verification

Resends the verification email. Rate-limited to 3 requests per hour per account. Always returns 200 to prevent email enumeration.

Request Body schema: application/json
required
email
required
string <email> <= 254 characters

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "code": "RATE_LIMITED",
  • "message": "Too many requests. Retry after the indicated period.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Request Device Authorization Code (RFC 8628)

Step 1 of the Device Authorization Grant for input-constrained devices (TVs, consoles). Returns a device_code and short user_code for secondary-device activation.

Request Body schema: application/x-www-form-urlencoded
required
client_id
required
string
scope
required
string

Responses

Response samples

Content type
application/json
{}

Poll Device Token (RFC 8628)

Step 2 — device polls this endpoint using device_code at the specified interval. Returns tokens when the user completes activation on a second screen, or authorization_pending / slow_down while waiting.

Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string
Value: "urn:ietf:params:oauth:grant-type:device_code"
device_code
required
string
client_id
required
string

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 900,
  • "refresh_token": "string",
  • "scope": "openid profile content:read subscription:read watchlist devices drm",
  • "id_token": "string"
}

Federated Social Login

Exchange an upstream OIDC ID token (Google, Apple, Facebook) for an EncoraStream token set. Creates an account on first use.

path Parameters
provider
required
string
Enum: "google" "apple" "facebook"
Request Body schema: application/json
required
id_token
required
string

OIDC ID token / authorization code issued by the upstream identity provider.

nonce
string or null

Responses

Request samples

Content type
application/json
{
  • "id_token": "string",
  • "nonce": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 900,
  • "refresh_token": "string",
  • "scope": "openid profile content:read subscription:read watchlist devices drm",
  • "id_token": "string"
}

Register a New User

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.

Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "pa$$word_q",
  • "display_name": "string",
  • "phone": "string",
  • "locale": "en-US",
  • "country_code": "US",
  • "accept_terms": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "email_verified": true,
  • "display_name": "string",
  • "phone": "string",
  • "phone_verified": true,
  • "avatar_url": "http://example.com",
  • "locale": "en-US",
  • "timezone": "America/New_York",
  • "country_code": "US",
  • "preferred_language": "en",
  • "status": "active",
  • "roles": [
    ],
  • "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"
}

List Active Sessions

Returns all active login sessions for the current account.

Authorizations:
OAuth2PKCE

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Revoke a Specific Session

Terminates a single session. Use current as the session_id to revoke the active session (logout).

Authorizations:
OAuth2PKCE
path Parameters
session_id
required
string

Responses

Response samples

Content type
application/json
{
  • "code": "UNAUTHORIZED",
  • "message": "Access token is missing or invalid.",
  • "request_id": "018fde1a-9b2c-7f3e-8d4a-2b5c6e7f8a9b"
}

Setup MFA (TOTP)

Initiates TOTP MFA enrollment. Returns a provisioning_uri and QR code data URL. MFA is not active until confirmed via POST /auth/mfa/verify.

Authorizations:
OAuth2PKCE

Responses

Response samples

Content type
application/json
{}

Verify TOTP Code (Complete MFA Setup or Step-Up Auth)

Verifies a TOTP code. Used to:

  1. Complete MFA enrollment after /auth/mfa/setup.
  2. Satisfy MFA challenge during login (step-up authentication). Returns a short-lived step-up token on success.
Authorizations:
OAuth2PKCE
Request Body schema: application/json
required
totp_code
required
string [ 6 .. 8 ] characters ^\d+$

Responses

Request samples

Content type
application/json
{
  • "totp_code": "string"
}

Response samples

Content type
application/json
{
  • "step_up_token": "string",
  • "expires_in": 300
}

Disable MFA

Removes MFA from the account. Requires a valid TOTP code for confirmation. All sessions are revoked.

Authorizations:
OAuth2PKCE
Request Body schema: application/json
required
totp_code
required
string [ 6 .. 8 ] characters ^\d+$

Responses

Request samples

Content type
application/json
{
  • "totp_code": "string"
}

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "Resource not found.",
  • "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  • "documentation_url": "http://example.com"
}

Get MFA Recovery Codes

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.

Authorizations:
OAuth2PKCE

Responses

Response samples

Content type
application/json
{
  • "codes": [
    ],
  • "generated_at": "2019-08-24T14:15:22Z"
}

Regenerate MFA Recovery Codes

Invalidates all existing recovery codes and issues a new set. Requires TOTP confirmation.

Authorizations:
OAuth2PKCE
Request Body schema: application/json
required
totp_code
required
string [ 6 .. 8 ] characters ^\d+$

Responses

Request samples

Content type
application/json
{
  • "totp_code": "string"
}

Response samples

Content type
application/json
{
  • "codes": [
    ],
  • "generated_at": "2019-08-24T14:15:22Z"
}

DeviceAuth

OAuth 2.0 Device Authorization Grant

SocialAuth

Social / federated login

Registration

New user account creation

Sessions

Active session listing and revocation

MFA

Multi-factor authentication setup, verification, and recovery