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 leastone 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: Unparseable JSON or missing required fields.
  • PBS_ACCOUNT_CONFIG_NOT_FOUND: Station does not have a related PBS Account Config.
  • 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 unhandleable error from the upstream API.

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: Unparseable JSON or missing required fields.
  • PBS_ACCOUNT_CONFIG_NOT_FOUND: Station does not have a related PBS Account Config.
  • 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 unhandleable error from the upstream API.

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: Unparseable JSON or missing required fields.
  • PBS_ACCOUNT_CONFIG_NOT_FOUND: Station does not have a related PBS Account Config.
  • 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 unhandleable error from the upstream API.

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 recieve 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: Unparseable JSON or missing required fields.
  • PBS_ACCOUNT_CONFIG_NOT_FOUND: Station does not have a related PBS Account Config.
  • 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 unhandleable error from the upstream API.

Public Media SSO authorization

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.
resturnUri	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: Unparseable JSON or missing required fields.
  • PBS_ACCOUNT_CONFIG_NOT_FOUND: Station does not have a related PBS Account Config.

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 invlaid OAuth2 state value.
  • DEVICE_NOT_FOUND: Device not found with state data.
  • PBS_ACCOUNT_CONFIG_NOT_FOUND: Station does not have a related PBS Account Config.
  • STATION_NOT_FOUND: Unknown station call sign.