Advanced Token Authentication

Operations related to using advanced token authentication, known in Wowza Video as a default playback token behavior option, with videos.

Use token authentication when distributing valuable or sensitive video content to audiences to ensure that only authorized users can access the content within the intended application. This allows for protection of intellectual property, compliance with regulations, and the ability to maintain control over content distribution. The token is embedded in the videos' embed URLs.

Through the UI or Wowza Video API, you can choose one of the following options for token authentication of a video:

NO_TOKEN - Video files are accessible and can be downloaded and played by anyone at any time. This is the default.
BASIC_TOKEN - The platform automatically creates tokenized video URLs. This setting makes it hard for a viewer to extract the video URL and store it for usage in unintended applications over time since the embed URL, which has the token as part of the URL, will only be playable for 48 hours. The token auto renews after 48 hours when used in the intended application.
ADVANCED_TOKEN - You add the stream's JS embed code (Share Stream) and a token to your site to provide tokenization. The protections are similar to those for the Basic Token option except you customize the time limit, geographical limits, etc. during token creation.
FOLLOW_DEFAULT: - The token behavior is based on the Default Playback Token Behavior setting you selected for your Wowza account. See the Org Settings page in Wowza Video article for where to set this configuration.

Note: You'll use the /videos endpoints to update and review the token authentication enums bulleted above.

Before selecting to use the ADVANCED_TOKEN, you must, first, either:

Generate a key id via the Wowza Video API, then customize and generate a token via the Wowza Video 2.0 API to add to your site. You'll need the key id to create and sign the token.
Generate a key id and key via the Wowza Video 2.0 API, then customize and generate a standard common access token (CAT) through the means you usually use to create tokens to add to your site. You'll need the key id and key to create and sign the token.

After you have your playback token, you add the video JS-embed and the playback token to your site if you're going to use the ADVANCED_TOKEN option. The JS-embed code automatically adds the player and related video to your site. See the section on <a href="how to embed the player and video".

Create a playback token key

This operation creates a playback token key that includes a key id and key value. You use one or both of these parameters to create a playback token for advanced token authentication.

Before using the ADVANCED_TOKEN option as your token authentication for a video, you must do one of the following:

Generate a playback token key that has a key id using this endpoint in the Wowza Video API, then customize and generate a token via the Wowza Video 2.0 API to add to your site. You'll need the key id to create and sign the token.
Generate a playback token key that has a key id and key value using this endpoint in the Wowza Video 2.0 API, then customize and generate a standard common access token (CAT) through the means you usually use to create tokens to add to your site. You'll need the key id and key to create and sign the token.
The key value is only returned in this endpoint so keep it in a place that you can access it later when you create your playback token.

Request

Request Body schema: application/json
required

Provide the details of the playback token keys to create in the body of the request.

object (CreatePlaybackTokenKeyRequestModel)

name

required

string

The name of the playback token key for the organization.

Responses

200

Success

Response Schema: application/json

object (CreatePlaybackTokenKeyResponseModel)

id	string Unique identifier for the playback token key. The id will contain the organization id in the key id.
organization_id	string The organization id for Wowza Video.
name	string The name of the key for the organization.
created_at	string <date-time> The key creation timestamp.
value	string The key value for the key. If you generate a playback token for advanced token authentication by creating a standard common access token (CAT) through the means you usually use to create tokens, you'll need to add this key value during token creation to sign the token. The key value is only returned in this endpoint to keep it in a place that you can access it later when you create your playback token.

401

Unauthorized

403

Forbidden

404

Not Found

410

Gone

422

Unprocessable Entity

post/playback_tokens/keys

Request samples

Payload
Shell
JavaScript
Java
Python

application/json

{"playback_token_key": {"name": "Key name"
}
}

Response samples

application/json

{"playback_token_key": {"id": "51cd5c07-1583-4f5e-bd81-f1aa11510ea9",
"organization_id": 123456,
"name": "key name",
"created_at": "2020-01-01T12:33:22Z",
"value": "string"
}
}

Fetch playback token keys

This operation shows details for playback token keys you've created that are available in Wowza Video for your account. The details include a key id which you use to create a playback token for advanced token authentication.

Before using the ADVANCED_TOKEN option as your token authentication for a video, you must do one of the following:

Generate a playback token key that has a key id using the POST /playback_tokens/keys endpoint in the Wowza Video API, then customize and generate a token via Wowza Video 2.0 API to add to your site. You'll need the key id to create and sign the token.
Generate a playback token key that has a key id and key value using the POST /playback_tokens/keys endpoint in the Wowza Video 2.0 API, then customize and generate a standard common access token (CAT) through the means you usually use to create tokens to add to your site. You'll need the key id and key to create and sign the token. You received the key value in the response when you created the playback token key.

Request

query Parameters

query

string

Name is the only searchable field.

Limit to a specific field with a colon (:).

If you have multiple search terms you can use pipe (|) to separate the search terms.

Examples:

Query	Description
`query=foo`	Searches name & description field for `foo`.

page

integer

Returns a paginated view of results from the HTTP request. Specify a positive integer to indicate which page of the results should be displayed. The default is 1.

For more information and examples, see Get paginated query results with the Wowza Video REST API.

per_page

integer

For use with the page parameter. Indicates how many records should be included in a page of results. A valid value is any positive integer. The default and maximum value is 1000.

Responses

200

Successful operation

Response Schema: application/json

	Array of objects (PlaybackTokenKeyResponseModel) The list of playback token keys.
	object Page information for the results generated by the query.

401

Unauthorized

403

Forbidden

404

Not Found

410

Gone

get/playback_tokens/keys

Request samples

Shell
JavaScript
Java
Python

// Using cURL
curl -H "Authorization: Bearer ${WV_JWT}" \
  
  -H "Content-Type: application/json" \
  -X "GET" \
  "${WV_HOST}/api/v2.0/playback_tokens/keys"

Response samples

application/json

{"playback_token_keys": [{"id": "string",
"organization_id": "string",
"name": "string",
"created_at": "2020-01-01T12:33:22Z"
}
],
"pagination": {"payload_version": 0,
"total_records": "",
"page": "",
"per_page": "",
"total_pages": "",
"page_first_index": "",
"page_last_index": ""
}
}

Delete a playback token key

This operation deletes a playback token key.

Request

path Parameters

required

string

Unique identifier, or key id, for the playback token keys.

Example: 51cd5c07-1583-4f5e-bd81-f1aa11510ea9

Responses

204

No content

401

Unauthorized

403

Forbidden

404

Not Found

410

Gone

422

Unprocessable Entity

delete/playback_tokens/keys/{id}

Request samples

Shell
JavaScript
Java
Python

// Using cURL
curl -H "Authorization: Bearer ${WV_JWT}" \
    
  -H "Content-Type: application/json" \
  -X "DELETE" \
  "${WV_HOST}/api/v2.0/playback_tokens/keys/2aa3343e-2fb5-42c3-8671-b52c24b7c3e2"
}'

Response samples

application/json

{"Example Response 1": {"meta": {"status": 401,
"code": "ERR-401-NoApiKey",
"title": "No API Key Error",
"message": "No API key sent in header.",
"description": "",
"links": [ ]
}
},
"Example Response 2": {"meta": {"status": 401,
"code": "ERR-401-NoAccessKey",
"title": "No Access Key Error",
"message": "No access key sent in header.",
"description": "",
"links": [ ]
}
},
"Example Response 3": {"meta": {"status": 401,
"code": "ERR-401-InvalidApiKey",
"title": "Invalid Api Key Error",
"message": "Invalid API key.",
"description": "",
"links": [ ]
}
},
"Example Response 4": {"meta": {"status": 401,
"code": "ERR-401-InvalidAccessKey",
"title": "Invalid Access Key Error",
"message": "Invalid access key.",
"description": "",
"links": [ ]
}
},
"Example Response 5": {"meta": {"status": 401,
"code": "ERR-401-BadAccountStatus",
"title": "Bad Account Status Error",
"message": "Your account's status doesn't allow this action.",
"description": "",
"links": [ ]
}
},
"Example Response 6": {"meta": {"status": 401,
"code": "ERR-401-FeatureNotEnabled",
"title": "Feature Not Enabled Error",
"message": "This feature isn't enabled.",
"description": "",
"links": [ ]
}
},
"Example Response 7": {"meta": {"status": 401,
"code": "ERR-401-TrialExceeded",
"title": "Bad Billing Status Error",
"message": "Your billing status needs attention. You can't start or add live streams until your billing status is updated.",
"description": "",
"links": [ ]
}
},
"Example Response 8": {"meta": {"status": 401,
"code": "ERR-401-ExpiredToken",
"title": "JWT is expired",
"message": "Token has exired.",
"description": "",
"links": [ ]
}
},
"Example Response 9": {"meta": {"status": 401,
"code": "ERR-401-InvalidToken",
"title": "JWT is invalid",
"message": "Token is invalid.",
"description": "",
"links": [ ]
}
}
}

Create a playback token

This operation creates a playback token for use with advanced token authentication.

You'll use the PATCH /videos/{id} endpoint to select ADVANCED_TOKEN authentication for your video after you have the playback token. Then, you'll add the token into your player site along with the JS-embed for the video.

Before using the ADVANCED_TOKEN option as your token authentication for a video, you must do the following:

Generate a playback token key that has a key id using the POST /playback_tokens/key in the Wowza Video API, then customize and generate a token via this endpoint in the Wowza Video 2.0 API to add to your site. You'll need the key id to create and sign the token.

Request

Request Body schema: application/json

key_id required	string The unique identifier for the id key returned when you used the POST /playback_tokens/keys endpoint to create a playback token key. This key will sign the token you create.
exp required	integer <int64> The expiration time of the token which is the unix timestamp in seconds. If the current time is greater than the expiration time, the request will be considered invalid.
nbf	integer <int64> The time before which the token must not be accepted for processing which is the unix timestamp in seconds.
iat	integer <int64> The issue date of the token which is the unix timestamp in seconds.
iss	string The issuer of the token.
sub	string The subject of the token.
aud	string The audience of the token.
cti	string Uniquely identifies a token to help prevent reuse or replay attacks.
	Array of objects (CatnipClaim) The IP address of the network for which the token was issued. The array contains objects with tag and value. Each object represents a catnip claim. The max number of items allowed is 5 and the minimum is zero.
	object A map of URIs to which the token applies. The maximum number of items allowed is five. The object contains an array of key and value.
catgeoiso3166	Array of strings The ISO3166 country codes from which the token was issued. Optionally, followed by a hyphen and a region code. the maximum number allowed is five.
catv	integer <int323> The version of the token. The integer must be 1.

Responses

200

Success

Response Schema: application/json

token

string

The unique identifier for the playback token.

Add this token to your site along with the JS-embed for the video to use advanced token authentication. You must also use PATCH /videos/{id} to select ADVANCED_TOKEN as your authentication type for the video after you create the playback token.

401

Unauthorized

403

Forbidden

404

Not Found

410

Gone

422

Unprocessable Entity

post/playback_tokens

Request samples

Payload
Shell
JavaScript
Java
Python

application/json

{"key_id": "51cd5c07-1583-4f5e-bd81-f1aa11510ea9",
"exp": 1679816499,
"nbf": 1679816499,
"iat": 1679816499,
"iss": "my-issuer",
"sub": "subscriber1234",
"aud": "my-audience",
"cti": "unique-token-id",
"catnip": [{"tag": 52,
"value": [24,
{"0": 188,
"1": 4,
"2": 23
}
]
}
],
"catu": {"property1": [ ],
"property2": [ ]
},
"catgeoiso3166": [["US",
"CA-ON"
]
],
"catv": 1
}

Response samples

application/json

{"token": "string"
}

Advanced Token Authentication

Create a playback token key

Request Body schema: application/jsonrequired

Response Schema: application/json

Fetch playback token keys

query Parameters

Response Schema: application/json

Delete a playback token key

path Parameters

Create a playback token

Request Body schema: application/json

Response Schema: application/json

Request Body schema: application/json
required