PBS Account

PBS Account endpoints implement the new Public Media SSO API replacing the legacy PBS OAuth2 API.

On-device authentication

Perform on-device authentication with the following flow:

1. POST /deviceInit
2. Capture deviceId
3. If necessary, POST /pbsAccount/register
4. POST /pbsAccount/login (using deviceId from Step 1)
5. Capture showVppaScreen and viewer.id

If showVppaScreen == true:

1. Offer VPPA agreement to viewer (must be accepted, if declined return to login screen)
2. On accept, PATCH /pbsAccount/profile (using viewer.id from initial flow Step 5)
3. POST /deviceInit

POST /pbsAccount/register

Purpose

Register a new PBS Account user.

See Akamai - Complete traditional registration for details about the upstream API, but note that not all features are supported for PBS Account register.

Payload

Type

JSON in body.

Parameters

Parameter	Required	Type	Description
emailAddress	Yes	String	User email address.
firstName	Yes	String	User first name (1 - 25 characters).
lastName	Yes	String	User last name (1 - 25 characters).
password	Yes	String	Account password (8 - 90 characters, at least one letter and one number).
stationId	Yes	UUID	ID of the station associated with the request.

Responses

204 No Content

Indicates the account was created.

400 Bad Request

JSON body with:

• reason: Code string indicating the reason for the error:
  • BAD_PAYLOAD: Unparsable JSON or missing required fields.
  • PBS_ACCOUNT_ALREADY_EXISTS: PBS Account already registered with the requested email address.
  • VALIDATION_ERRORS: Field validation failed from the upstream API.
• validationErrors: Array of validation error strings for the viewer (when reason == VALIDATION_ERRORS).

500 Internal Server Error

Indicates an error from the upstream API could not be handled.

POST /pbsAccount/login

The pbsAccount.login webhook is sent on successful login.

Purpose

Log in a PBS Account user.

See Akamai - Supported authorization grant types for details about the client_credentials grant flow used for login.

See Public Media SSO - POST /v2/login_resolve/ for details about the upstream login finalization for Public Media SSO.

Payload

Type

JSON in body.

Parameters

Parameter	Required	Type	Description
deviceId	Yes	String	Device ID for the user logging in.
password	Yes	String	Account password.
stationId	Yes	UUID	ID of the station associated with the request.
username	Yes	UUID	Account username.

Responses

200 OK

JSON body with:

• showVppaScreen: Boolean indicator if the viewer requires a VPPA agreement and does not have one. When true, the FE must offer the VPPA agreement to the viewer before continuing.
• viewer: Information about the logged in viewer:
• id: Viewer ID.
• pbsAccountId: Viewer PBS Account ID

400 Bad Request

JSON body with:

• reason: Code string indicating the reason for the error:
  • BAD_PAYLOAD: Unparsable JSON or missing required fields.
  • VALIDATION_ERRORS: Field validation failed from the upstream API.
• validationErrors: Array of validation error strings for the viewer (when reason == VALIDATION_ERRORS).

500 Internal Server Error

Indicates an error from the upstream API that could not be handled.

PATCH /pbsAccount/profile

Purpose

Updates a PBS Account profile.

Currently, this endpoint only supports updating the VPPA accepted status of a profile.

See Public Media SSO - PATCH /v2/user/profile/ for details about the upstream API.

Payload

Type

JSON in body.

Parameters

Parameter	Required	Type	Description
profile	Yes	Object	Profile fields to update. Values keyed by profile field name.
∟vppa_accepted	No	Boolean	Whether the viewer has accepted the VPPA agreement.
stationId	Yes	UUID	ID of the station associated with the request.
viewerId	Yes	UUID	Viewer ID to update the associated PBS Account profile for.

Responses

204 No Content

Indicates the profile was updated.

400 Bad Request

JSON body with:

• reason: Code string indicating the reason for the error:
  • BAD_PAYLOAD: Unparsable JSON or missing required fields.
  • VIEWER_NOT_FOUND: Viewer not found for provided ID.
  • VALIDATION_ERRORS: Field validation failed from the upstream API.
• validationErrors: Array of validation error strings for the viewer (when reason == VALIDATION_ERRORS).

500 Internal Server Error

Indicates an error from the upstream API that could not be handled.

POST /pbsAccount/forgotPassword

Purpose

Initiates a forgot password flow for a PBS Account.

See Akamai - Send a reset password link for details about the upstream API, but note that not all features are supported for PBS Account forgot password flow.

Payload

Type

JSON in body.

Parameters

Parameter	Required	Type	Description
emailAddress	Yes	String	Email address associated with the PBS Account.
stationId	Yes	UUID	ID of the station associated with the request.

Responses

204 No Content

Indicates the forgot password flow was initiated.

The user will receive an email and continue the reset process in a web browser.

400 Bad Request

JSON body with:

• reason: Code string indicating the reason for the error:
  • BAD_PAYLOAD: Unparsable JSON or missing required fields.
  • VALIDATION_ERRORS: Field validation failed from the upstream API.
• validationErrors: Array of validation error strings for the viewer (when reason == VALIDATION_ERRORS).

500 Internal Server Error

Indicates an error from the upstream API that could not be handled.

Public Media SSO authorization

Web-based authorization flow

Perform web-based SSO authorization with the following flow:

1. POST /deviceInit
2. Capture deviceId
3. POST /pbsAccount/sso/init (using deviceId from Step 2)
4. Use the returned OAuth2 client configuration values to run the SSO authorization flow in a web browser

This flow is intended for frontends that can run a custom OAuth2 PKCE flow in a web browser. VPPA agreement is handled by the upstream SSO flow and does not require any additional steps.

Failure handling

If the authorization flow fails, the error behavior differs based on whether the OAuth state has been matched. If it has, the viewer will be redirected to the returnUri provided in Step 3 when possible with an oauth_error query parameter indicating the error.

Possible values for the oauth_error query parameter are:

• ACCESS_TOKEN_MISSING: Unable to retrieve access token from PBS Account OAuth API.
• DEVICE_UPDATE_FAILURE: Unable to update device (invalid device ID or query error).
• PBS_ACCOUNT_NOT_FOUND: PBS Account ID not found.
• VIEWER_UPDATE_FAILURE: Unable to update viewer.

If the state has not been matched, the viewer will receive a 400 Bad Request response with a JSON body indicating the error. This behavior ensures that the viewer is not redirected to an untrusted returnUri when the OAuth2 state is invalid.

Possible values for oauth_error JSON response are:

• DEVICE_NOT_FOUND: Device not found with provided state.
• OAUTH2_STATE_FAILED: Invalid OAuth2 state value.
• STATION_NOT_FOUND: Station not found for provided stationId.
• VPPA_CALLBACK_COOKIE_FAILED: Invalid VPPA callback cookie value.

Success handling

After authorization, the viewer will be redirected to the returnUri provided in Step 3. The following query parameters will be appended to the returnUri:

1. device_id: The original device ID provided in Step 3 of the flow.
2. pbs_account_id: The PBS Account ID of the logged in viewer.
3. membership_id: The PBS Passport membership ID of the logged in viewer (if available).
4. success: Always set to 1 to indicate the authorization flow completed successfully.

After success, implementors should re-run POST /deviceInit to refresh the device state and retrieve the logged in viewer information.

POST /pbsAccount/sso/init

Purpose

Starts the OAuth2 authorization flow for a PBS Account for frontends using a custom OAuth2 PKCE flow.

Payload

Type

JSON in body.

Parameters

Parameter	Required	Type	Description
deviceId	Yes	String	Device ID for the user logging in.
returnUri	Yes	String	URI to return the user to from the SSO callback.
stationId	Yes	UUID	ID of the station associated with the request.

Responses

200 OK

JSON body with OAuth2 client configuration values:

• authorizationEndpoint: Authorization endpoint URL.
• clientId: Public client ID.
• codeChallenge: Code challenge value.
• codeChallengeMethod: Code challenge method.
• redirectUri: Callback URI.
• scopes: Scopes to request.
• state: Random state value.

400 Bad Request

JSON body with:

• reason: Code string indicating the reason for the error:
  • BAD_PAYLOAD: Unparsable JSON or missing required fields.

404 Not Found

Device note found with provided deviceId.

GET /pbsAccount/sso/login

The pbsAccount.ssoLogin webhook is sent on successful SSO authorization (during callback processing).

Purpose

Starts the OAuth2 authorization flow for a PBS Account for frontends using device-code based authorization.

See Public Media SSO - POST /v2/login_resolve/ for details about the upstream login finalization for Public Media SSO.

Payload

Type

Search parameters.

Parameters

Parameter	Required	Type	Description
provider	Yes	String	Authorization provider.
state	Yes	String	OAuth2 state value.

Responses

302 Found

Redirect to the requested authorization provider.

400 Bad Request

JSON body with:

• reason: Code string indicating the reason for the error:
  • BAD_PAYLOAD: Missing required fields or invalid OAuth2 state value.
  • DEVICE_NOT_FOUND: Device not found with state data.
  • STATION_NOT_FOUND: Unknown station call sign.