A playback credential is a time-sensitive, video-specific token that cannot be reused. If the credential expires or is incorrect, the playback URL cannot be retrieved, making this method suitable for high-security playback scenarios.
Usage notes
ApsaraVideo Player supports playback via playback credentials. Third-party players do not support this method.
A playback credential is valid for 100 seconds by default (maximum 3000 seconds). It retrieves the playback URL for a specific video only and cannot be shared or reused. If the credential expires, you must handle the refresh logic in your application.
The validity period of a playback credential is not the same as the validity period of a playback URL (if URL signing is enabled). The latter can be customized with no upper limit.
If you use Alibaba Cloud Video Encryption (Private Encryption), videos can only be played using the ApsaraVideo Player software development kit (SDK).
Validity parameters: AuthInfoTimeout vs AuthTimeout
Two validity parameters apply, depending on which API you call:
When calling the GetVideoPlayAuth API to obtain a playback credential, the validity period is controlled by the AuthInfoTimeout parameter.
When calling the GetPlayInfo API to obtain a playback URL, the validity period is controlled by the AuthTimeout parameter.
Do not confuse these two parameters: AuthInfoTimeout governs how long the PlayAuth remains valid, while AuthTimeout governs how long the generated playback URL remains accessible.
Front-end authTimeout vs server-side validity
The authTimeout parameter on the player SDK (front-end) controls only the local cache refresh behavior. It does not override the validity period returned by the server.
The ExpireTime field in the PlayAuth is the authoritative expiration timestamp and determines actual playback behavior:
If the server-side credential has expired (ExpireTime has passed), authentication fails regardless of the front-end authTimeout setting.
If the server-side credential is still valid, playback can continue even if the front-end authTimeout has elapsed, provided new credential requests succeed.
Renewal mechanism for long videos
The maximum validity period for a playback credential is 3000 seconds. For longer videos, refresh the PlayAuth 10 to 30 seconds before expiration using the player SDK's credential refresh methods (for example, Aliplayer provides replayByVidAndPlayAuth or loadByUrl). Do not wait until the exact expiration moment, as network latency may cause playback interruption.
High concurrency caching strategy
The GetVideoPlayAuth API has a per-user QPS limit of 360 requests per second. In high-concurrency scenarios, implement a server-side caching strategy:
Cache the PlayAuth and reuse it within its validity period to reduce API calls.
Credential expiration only affects playback URL retrieval. Once a playback URL has been obtained, playback continues even if the credential expires.
Browser compatibility
If playback works in Chrome but fails in Edge, first check the video encoding format compatibility, then verify the validity of the playback credential.
Credential expiration error handling
When the client (for example, the Android SDK) reports a "playauth is expired" error, add credential expiration listeners and automatic refresh logic in your application. For detailed integration steps, see the advanced configuration documentation for each platform's SDK.
Overall process
The following shows how to obtain a playback credential and play a video, using a CDN-accelerated domain name as an example.
The client sends a VideoId to the server to request a playback credential.
Your server calls the GetVideoPlayAuth operation using the server-side SDK to obtain the playback credential.
The VOD service returns the playback credential to the server.
The server returns the playback credential to the client.
The client player requests a playback URL from the VOD service using the returned credential.
The VOD service returns the playback URL to the client.
The client requests the playback resource from the CDN node using the playback URL.
If the CDN node does not have the resource or the cached resource has expired, it retrieves the resource from the origin OSS bucket.
The OSS bucket returns the resource to the CDN node, which caches it.
The CDN node delivers the media resource to the client.
Next steps
Alibaba Cloud provides player SDKs for Web, Android, iOS, Flutter, and HarmonyOS, all of which support credential-based playback. Select the documentation for your platform:
FAQ
Does the Web player SDK support JWT authentication tokens?
No. The Web player SDK supports only the VID + PlayAuth playback method. If you encounter playback failures with a locally generated JWT Auth, switch to the standard PlayAuth method.
Why does GetPlayInfo return an error indicating the video status is invalid or under review?
A video must meet both of the following conditions to obtain playback information:
The main status (Status) is Normal.
The audit status (AuditStatus) is Normal.
If the status is UploadSucc or the audit status is Init, wait for transcoding to complete and the review to pass. You can use the GetVideoInfo API to query the latest video status and check your global audit settings.
Why must I specify the format as mp4 for playback?
This is typically caused by HLS format compatibility issues in older player SDK versions. Upgrade to the latest player SDK version or test with the official demo code.
How do I obtain video resolution identifiers (LD, HD, SD) on Android?
Resolution identifiers are only returned by the server when using the playback credential method (VidSts or VidAuth). If you use the URLSource playback method directly, resolution identifiers will not be available.
Does the VID + PlayAuth method support playing resources from third-party cloud storage?
No. The VID + PlayAuth method supports only videos uploaded to the Alibaba Cloud VOD media asset library. To play third-party resources, first migrate or upload them to Alibaba Cloud VOD to generate a VID.