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:
POST /deviceInit- Capture
deviceId - If necessary,
POST /pbsAccount/register POST /pbsAccount/login(usingdeviceIdfrom Step 1)- Capture
showVppaScreenandviewer.id
If showVppaScreen == true:
- Offer VPPA agreement to viewer (must be accepted, if declined return to login screen)
- On accept,
PATCH /pbsAccount/profile(usingviewer.idfrom initial flow Step 5) 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
- 400 Bad Request
- 500 Internal Server Error
Indicates the account was created.
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 (whenreason==VALIDATION_ERRORS).
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
- 400 Bad Request
- 500 Internal Server Error
JSON body with:
showVppaScreen: Boolean indicator if the viewer requires a VPPA agreement and does not have one. Whentrue, 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
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 (whenreason==VALIDATION_ERRORS).
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
- 400 Bad Request
- 500 Internal Server Error
Indicates the profile was updated.
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 (whenreason==VALIDATION_ERRORS).
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
- 400 Bad Request
- 500 Internal Server Error
Indicates the forgot password flow was initiated.
The user will receive an email and continue the reset process in a web browser.
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 (whenreason==VALIDATION_ERRORS).
Indicates an error from the upstream API that could not be handled.
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. |
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
- 400 Bad Request
- 404 Not Found
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.
JSON body with:
reason: Code string indicating the reason for the error:BAD_PAYLOAD: Unparsable JSON or missing required fields.
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
- 400 Bad Request
Redirect to the requested authorization provider.
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.