• Skip to Search
  • Skip to Content
  • Skip to Side Navigation
Getting StartedSDK ReferenceGlossary
  • Home
  • Getting Started
  • SDK Reference
  • Portal
  • How-To
  • Troubleshooting
  • FAQs
  • Reference
  • Glossary
REST API
Web SDK
Android SDK
iOS SDK
Unity SDK
React Native SDK
EdgeAuth SDK
  • Overview
  • Usage

Using EdgeAuth

Once you have integrated the EdgeAuth library into your backend, generate tokens as described below.

Terms

  • Phenix Customer - Someone wanting to use the Phenix infrastructure for streaming

  • Customer token service - Code written and hosted by the Phenix customer

  • User - An end user wanting to publish or view a stream

  • Phenix Platform - Infrastructure delivering the content stream

  • Token - Cryptographically signed text

  • Other terms as described in the Phenix glossary of terms

Token Types

There are four types of tokens for publishing and streaming:

Token TypePermitsInclude in Call to Create
authTokenCreation of a sessionforAuthenticationOnly()
streamTokenConsumption of a streamforStreamingOnly()
publishTokenCreation of a streamforPublishingOnly()
edgeToken (is both an authToken and a streamToken)Creation of a session and consumption of streamsdefault / none
edgeToken: The edgeToken is a default token without any specific restrictions specified.

All that is needed for playback or publishing is a token from the EdgeAuth library, and all that is needed to generate that token is the Application ID and Secret, as well as information about Channels or Rooms.  You do not need any user information unless you (optionally) want to restrict the token based on user information, e.g., to a particular session ID. See below for details about restricting tokens.

Token Designation: When creating tokens, you need to designate a Channel or a Room (by ID or by Alias). If a Channel or Room is not designated, use of the token will result in Authentication failure as Unauthorized.

In other words, a token generated with an Application ID and secret, but no further restrictions other than expiration time, does not cause an error in the library. This token would allow authentication, but does NOT allow streaming for any channel. A token with no Channel ID, Room ID, Channel Alias, or Room Alias designated will fail to stream. Stream tokens for subscribing cannot be used for both streaming and authorization without any configurations/constraints set.

Call Flow Diagrams

An example call flow for an authorization using an Edge token (which combines both authToken and streamToken) to join a Room or a Channel is shown below.

edge_token_join

An example call flow for a session-based token flow to join a Room or Channel is shown below. The use of this flow is discussed in the following section.

session_token_join

See the discussion below for details on using the AuthToken when initializing the SDK.

Token Constraints

The design of tokens depends on business logic needs. Token creators can decide how narrow a token's scope is.

Note that the applicationId for the publishing and subscribing tokens must match. For example, if publishing is using an applicationId of mycompany.com, the applicationId used when creating tokens for subscribing must also be mycompany.com.

User and Stream Constraints

Tokens can optionally be restricted by any combination of the following:

  • User Information

    • User Session ID (sessionId)

    • User IP (remoteAddress)

  • Publishing/Subscribing Stream Information

    • Origin Stream (originStreamId) - Provide this to create a "view" token; otherwise, a publish token is generated.

    • Channel ID (channelId)

    • Channel Alias (channelAlias)

    • Room ID (roomId)

    • Room Alias (roomAlias)

All of the above options are set when the token is created by the EdgeAuth TokenBuilder library. The library is currently available for the following platforms:

  • Java

  • Node.js

  • PHP

  • DotNet

  • Python

For example, if authentication tokens are specific to a ChannelAlias, and there are multiple Channel Aliases to which a user needs access, the customer's token service needs to provide a separate Auth token for each ChannelAlias.

To add a constraint for sessionId to the above example of an Auth token restricted by ChannelAlias, access to an event with multiple Channel Aliases will require as many streaming tokens as there are Auth tokens.

If the only restriction is that an authorized user must not be able to share stream links with an unauthorized user, creating an Auth token with no restriction and a stream token with a session id restriction would be sufficient.

To allow a publisher to only provide content for a room or channel, the PCI needs to create a Publish token that contains the Room ID or Channel ID. If a user can provide content to multiple channels or rooms, multiple Publish tokens must be created.

If a user should be allowed to view content in multiple channels or rooms, the streams within those rooms and / or channels can be tagged with a specific tag, then the token can be restricted to only those streams with that tag via the "tag" restriction. If a new stream is created that has that same tag, any users having tokens that include that tag will be able to view it as well.

When you create EdgeAuth access tokens you can associate tags with each of them. This information can be used, for example, to map users to your internal accounting system or to generate billing reports for your customers. These tags will be available for filtering and as an output column in usage reports.

Supported Authentication Capabilities

ValueDescription
geo-country-allow=...Comma separated list of allowed countries in ISO 3166. Example: geo-country-allow=US,UK,DE
geo-country-deny=...Comma separated list of denied countries in ISO 3166. Example: geo-country-deny=US,IN,??
Unmapped IPs Even the best geo IP databases will not be able to map all IPs to a country. The special code `??` serves as the country code for any IP that is not mapped and can be used to identify unmapped IPs.

Token Expiration

Each token must have an expiration time after which it is no longer valid or a duration in seconds during which the token is valid. While the token is valid a user may subscribe to the stream, but after the token has expired the subscription request will fail. Likewise, a user may publish a stream while a publishing token is valid, but cannot begin publishing when the token is no longer valid.

Once subscribed to a stream the user may watch the stream until the stream stops or is terminated, even past the point of token expiration.

Tokens are evaluated when presented to the platform, such as when the SDK attempts to authenticate initially, or following an extended network interruption. If the token has expired, the session will not be authenticated and the application will need to obtain another token.

SDK Initialization with AuthToken

The use of an AuthToken when initializing the SDK varies based on the API Level and client platform. These are summarized in the following tables.

Web Platform

API LevelToken Usage
PCastExpresssdk.express.PCastExpress(authToken)
RoomExpresssdk.express.RoomExpress(authToken)
ChannelExpresssdk.express.ChannelExpress(authToken)

Android Platform

API LevelToken Usage
PCastExpressPCastExpressFactory.createPCastExpress(pcastExpressOptions); with options built by: PCastExpressFactory.createPCastExpressOptionsBuilder() .withAuthenticationToken
RoomExpressRoomExpressFactory.createRoomExpress(roomExpressOptions); with options built by: RoomExpressFactory.createRoomExpressOptionsBuilder() .withPCastExpressOptions(pcastExpressOptions) where pcastExpressOptions include .withAuthenticationToken
ChannelExpressChannelExpressFactory.createChannelExpress(channelExpressOptions); with options built by: ChannelExpressFactory.createChannelExpressOptionsBuilder() .withRoomExpressOptions(roomExpressOptions) with roomExpressOptions built by RoomExpressFactory.createRoomExpressOptionsBuilder() .withPCastExpressOptions(pcastExpressOptions) where pcastExpressOptions include .withAuthenticationToken

iOS Platform

API LevelToken Usage
PCastExpressPhenixPCastExpressFactory.createPCastExpress(pcastExpressOptions) with options built by: PhenixPCastExpressFactory.createPCastExpressOptionsBuilder() .withAuthenticationToken
RoomExpressPhenixRoomExpressFactory.createRoomExpress(roomExpressOptions); with options built by: PhenixRoomExpressFactory.createRoomExpressOptionsBuilder() .withPCastExpressOptions(pcastExpressOptions) where pcastExpressOptions include .withAuthenticationToken
ChannelExpressPhenixChannelExpressFactory.createChannelExpress(channelExpressOptions); with options built by: PhenixChannelExpressFactory.createChannelExpressOptionsBuilder() .withRoomExpressOptions(roomExpressOptions) with roomExpressOptions built by PhenixRoomExpressFactory.createRoomExpressOptionsBuilder() .withPCastExpressOptions(pcastExpressOptions) where pcastExpressOptions include .withAuthenticationToken

Creating an Auth Token

Creating an Auth Token Request

Authentication tokens are generated using a POST request as shown.

Example request for creating an authentication token

HTTP
1POST /pcast/auth HTTP/1.1
2Host: pcast.phenixrts.com
3Accept: application/json
4Content-Type: application/json
5Content-Length: 68
6
7{
8 "applicationId": "<applicationId>",
9 "secret": "<secret>"
10}
cURL
1$ curl https://pcast.phenixrts.com/pcast/auth \
2-H "Accept: application/json" \
3-H "Content-Type: application/json" \
4-H "Content-Length: 68" \
5-X POST \
6-d '{
7 "applicationId": "<applicationId>",
8 "secret": "<secret>"
9 "capabilities": ["<capability>"]
10 }'

Request Headers

FieldValue
Acceptapplication/json
Content-Typeapplication/json
Content-Length68

Request Payload

FieldDescription
applicationIdYour application ID
secretYour application secret
capabilities (optional)An array of capabilities for the token

Supported Authentication Capabilities

ValueDescription
geo-country-allow=...Comma separated list of allowed countries in ISO 3166. Example: geo-country-allow=US,UK,DE
geo-country-deny=...Comma separated list of denied countries in ISO 3166. Example: geo-country-deny=US,IN,??
Unmapped IPs Even the best geo IP databases will not be able to map all IPs to a country. The special code `??` serves as the country code for any IP that is not mapped and can be used to identify unmapped IPs.

Creating an Auth Token Response

The platform will return a successful response that contains a "status" and an "authenticationToken" field. The HTTP status code is set according to the "status" field.

HTTP/1.1 200 OK

Response Headers

FieldValue
Content-Typeapplication/json; charset=utf-8
Content-Length52

Example response for authentication token requests

HTTP
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3Content-Length: 52
4
5{"status":"ok","authenticationToken":"us-east#VaTd"}
cURL
1{
2 "status":"ok",
3 "authenticationToken":"us-east#VaTd"
4}

Response Fields

FieldDescription
statusThe status of the request
authenticationTokenThe authentication token to be used by your client

Status Codes

HTTPStatusRetryDescription
200 OKokneverSuccessful request, "authenticationToken" is valid and ready to use.
400 Bad Requestnot providedneverIndicates an issue with the request itself.
401 UnauthorizedunauthorizedneverThe streaming platform was not able to authorize the provided credentials.
4XXvariesneverIndicates an issue with the request itself.
503 Service UnavailablecapacityonceThe system is temporarily overloaded. Please try again later.
5XXvariesonce immediately, then exponential backoffA transient server error.
Lifetime: Authentication tokens can be used for up to 1 hour.

Creating a Stream Token

Creating a Stream Token Request

Stream tokens are generated sending a POST request as shown.

If you provide an "originStreamId", a view token is generated. Otherwise, a publish token is generated.

Example request for creating a stream token

HTTP
1POST /pcast/stream HTTP/1.1
2Host: pcast.phenixrts.com
3Accept: application/json
4Content-Type: application/json
5Content-Length: 194
6
7{
8 "applicationId": "<applicationId>",
9 "secret": "<secret>",
10 "sessionId": "<sessionId>",
11 "originStreamId": "<originStreamId>",
12 "capabilities": [
13 "<capability>"
14 ]
15}
cURL
1$ curl https://pcast.phenixrts.com/pcast/stream \
2-H "Accept: application/json" \
3-H "Content-Type: application/json" \
4-H "Content-Length: 138" \
5-X POST \
6-d '{
7 "applicationId": "<applicationId>",
8 "secret": "<secret>",
9 "sessionId": "<sessionId>",
10 "originStreamId": "<originStreamId>",
11 "capabilities": ["<capability>"]
12 }'

Request Headers

FieldValue
Acceptapplication/json
Content-Typeapplication/json
Content-Length138

Request Fields

FieldDescription
applicationId (required)Your application ID
secret (required)Your application secret
sessionId (required)The session ID of the client that you are generating this token for
originStreamId (optional)The stream ID of the published stream that you want to make available for viewing (omitted when creating a publish token)
capabilities (optional)An array of capabilities for the new stream

Creating a Stream Token Response

The platform will return a successful response that contains a "status" and a "streamToken" field. The HTTP status code is set according to the "status" field.

Response Headers

FieldValue
Content-Typeapplication/json; charset=utf-8
Content-Length44

Example response for stream token requests

HTTP
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3Content-Length: 44
4
5{"status":"ok","streamToken":"us-east#C1Nl"}
cURL
1{
2 "status":"ok",
3 "streamToken":"us-east#C1Nl"
4}

Response Fields

FieldDescription
statusThe status of the request
streamTokenThe stream token to be used by your client

Status Codes

HTTPStatusRetryDescription
200 OKokneverSuccessful request, "streamToken" is valid and ready to use.
400 Bad RequestvariesneverIndicates an issue with the request itself.
401 UnauthorizedunauthorizedneverThe streaming platform was not able to authorize the provided credentials.
404 Not Foundnot-found or origin-not-foundneverThe stream specified in the "originStreamId" is not known to the platform.
410 Goneorigin-endedneverThe stream specified in the "originStreamId" has ended.
4XXvariesneverIndicates an issue with the request itself.
503 Service UnavailablecapacityonceThe system is temporarily overloaded. Please try again later.
5XXvariesonce immediately, then exponential backoffA transient server error.
Page Content
    Copyright 2023 © Phenix RTS
    Privacy Policy | Terms of Service
    v2023-01-31T21:25:10