diff --git a/_assets/get-started/using-tokens/Delegated_upload_token.jpg b/_assets/get-started/using-tokens/Delegated_upload_token.jpg new file mode 100644 index 00000000..07e5cf6c Binary files /dev/null and b/_assets/get-started/using-tokens/Delegated_upload_token.jpg differ diff --git a/get-started/authentication-guide.md b/get-started/authentication-guide.md index d1916817..9af48a89 100644 --- a/get-started/authentication-guide.md +++ b/get-started/authentication-guide.md @@ -1,6 +1,9 @@ --- title: "Authentication and refresh tokens" +meta: + description: This page explains how clients should use access and refresh tokens to authenticate their requests to the api.video APIs. --- + Authentication and refresh tokens ================================= @@ -13,7 +16,7 @@ This guide shows the corresponding cURL commands for each part of the tutorial w {% endcapture %} {% include "_partials/callout.html" kind: "info", content: content %} -## Associated API reference documentation +## API documentation - [Authenticate](/reference/api/Advanced-authentication#get-bearer-token) - [Refresh token](/reference/api/Advanced-authentication#refresh-bearer-token) @@ -25,21 +28,33 @@ We offer blog content on this topic: - [Authentication steps](https://api.video/blog/tutorials/authentication-tutorial) - A walkthrough for authentication using cURL. - [You shall not pass: The benefits of token based authentication](https://api.video/blog/video-trends/you-shall-not-pass-the-benefits-of-token-based-authentication) - A discussion about what tokens are and what kinds of authentication api.video uses. +## Create an account + +Before you can start uploading your first video, you need to [create an api.video account](https://dashboard.api.video/register). + +Once you are logged in to the Dashboard, select the environment of your choice (sandbox or production) and copy your API key. + +![](/_assets/retrieve-api-key.png) + ## Choose an api.video client The clients offered by api.video include: -- [Go](https://github.com/apivideo/api.video-go-client) -- [PHP](https://github.com/apivideo/api.video-php-client) -- [JavaScript ](https://github.com/apivideo/api.video-nodejs-client) -- [Python](https://github.com/apivideo/api.video-python-client) -- [C#](https://github.com/apivideo/api.video-csharp-client) +- [NodeJS](/sdks/api-clients/apivideo-nodejs-client.md) +- [Python](/sdks/api-clients/apivideo-python-client.md) +- [PHP](/sdks/api-clients/apivideo-php-client.md) +- [Go](/sdks/api-clients/apivideo-go-client.md) +- [C#](/sdks/api-clients/apivideo-csharp-client.md) +- [Java](/sdks/api-clients/apivideo-java-client.md) +- [iOS](/sdks/api-clients/ios-api-client.md) +- [Android](/sdks/api-clients/android-api-client.md) -## Installation +## Install To install your selected client, do the following: {% capture samples %} + ```go go get github.com/apivideo/api.video-go-client ``` @@ -61,19 +76,9 @@ Using Nuget Install-Package ApiVideo ``` -{% endcapture %} -{% include "_partials/code-tabs.md" samples: samples %} - -## Retrieve your API key - -You'll need your API key to get started. You can sign up for one here: [Get your api.video API key!](https://dashboard.api.video/register). Then do the following: -1. Log in to the api.video dashboard. -2. From the list of choices on the left, make sure you are on **API Keys** -3. You will always be able to choose to use your Sandbox API key. If you want to use the Production API key instead, select a plan and enter your credit card information. -4. Grab the key you want, and you're ready to get started! - -![](/_assets/retrieve-api-key.png) +{% endcapture %} +{% include "_partials/code-tabs.html" content: samples %} ## Authenticate diff --git a/get-started/delegated-upload-tokens.md b/get-started/delegated-upload-tokens.md new file mode 100644 index 00000000..028b8e57 --- /dev/null +++ b/get-started/delegated-upload-tokens.md @@ -0,0 +1,649 @@ +--- +title: "Delegated upload tokens" +slug: "delegated-upload-tokens" +metadata: + description: This guide explains how to create, list, retrieve, and delete delegated upload tokens, and how to upload videos with them. +--- + +Using delegated upload tokens +============================================== + +You can upload videos using the traditional two-step process where you create a video container then upload your video into your container. You can also upload a video using a **delegated upload token**. This guide explains how to create, list, retrieve, and delete delegated upload tokens, and how to upload videos with them. + +In this type of upload, you retrieve a token from the tokens endpoint. You can then directly upload using the token upload endpoint. It's one step, and you don't provide anything except the file. You can update the metadata for the upload later. A benefit of a delegated token is that you define the TTL (time-to-live) value, so it expires only when you need it to. You can always use the token to upload. You can also create delegated tokens for others to use to do uploads. + +* Anyone who has a token can make an upload, so be careful how you set and manage tokens. +* You can create as many tokens as you need. +* If you do not include a TTL (time-to-live) value for a token, it lasts until you delete it. + +{% capture content %} +If you want to learn about regular or progressive uploads, check out the [Upload a video - regular, progressive, and bytes](/vod/upload-a-video-regular-upload) guide. +{% endcapture %} +{% include "_partials/callout.html" kind: "info", content: content %} + +## API documentation + +- [Upload Tokens](/reference/api/Upload-Tokens) +- [Upload with an upload token](/reference/api/Videos#upload-with-an-delegated-upload-token) + +## Resources + +We offer blog content on this topic: + +- [Delegated uploads](https://api.video/blog/tutorials/delegated-uploads) - **cURL** Walk through how to do a delegated upload using cURL. +- [Delegated uploads for videos large and small](https://api.video/blog/tutorials/delegated-uploads-for-videos-large-and-small-python) - **Python** Learn how to do a delegated upload using Python. + +## Create an account + +Before you can start uploading your first video, you need to [create an api.video account](https://dashboard.api.video/register). + +Once you are logged in to the Dashboard, select the environment of your choice (sandbox or production) and copy your API key. + +![](/_assets/retrieve-api-key.png) + +## Choose an api.video client + +The clients offered by api.video include: + +- [NodeJS](/sdks/api-clients/apivideo-nodejs-client.md) +- [Python](/sdks/api-clients/apivideo-python-client.md) +- [PHP](/sdks/api-clients/apivideo-php-client.md) +- [Go](/sdks/api-clients/apivideo-go-client.md) +- [C#](/sdks/api-clients/apivideo-csharp-client.md) +- [Java](/sdks/api-clients/apivideo-java-client.md) +- [iOS](/sdks/api-clients/ios-api-client.md) +- [Android](/sdks/api-clients/android-api-client.md) + +## Installation + +To install your selected client, do the following: + +{% capture samples %} + +```go +go get github.com/apivideo/api.video-go-client +``` +```php +composer require api-video/php-api-client +``` +```javascript +npm install @api.video/nodejs-client --save + +...or with yarn: + +yarn add @api.video/nodejs-client +``` +```python +pip install api.video +``` +```csharp +Using Nuget + +Install-Package ApiVideo +``` + +{% endcapture %} +{% include "_partials/code-tabs.html" content: samples %} + +## Generate a token for delegated upload + +Use this code sample to generate a token for use with a delegated upload. You can include a TTL (time-to-live) if you like. The token will expire after exceeding the set TTL. If you don't send in a TTL, your token will last until you choose to delete it. + +{% capture samples %} + +```curl +curl --request POST \ + --url https://ws.api.video/upload-tokens \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MTQxNDUuMjE2Mzc2LCJuYmYiOjE2NDI4MTQxNDUuMjE2Mzc2LCJleHAiOjE2NDI4MTc3NDUuMjE2Mzc2LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.GSDqqMzBxo-wOwl9IVbOnzevm8A6LSyaR5kxCWUdkEneSU0kIdoNfhwmXZBq5QWpVa-0GIT8JR59W6npNO-ayhaXmV3LA6EQpvv0mHd_dAhg3N8T96eC0ps0YIrkmw0_Oe6iRgEDI-wJ9nc6tQWi9ybbMHi1LDBjxW4rbFlq7G59C1QZGabd14QO7uqAUUSNqHC1l42z_m7BTK1AhFiBEXmMcfW7X0VmGcaEUy7NiNda8rmq_nrdvkxgN8KHguXzxMsw_4GE_d0eQwHcZvS1q-FebI6b8AoqpoltFOZvUACCrfXH_D_UPshHuJM3apXbD2dg_zQicc8oWBHVGiobLQ' \ + --header 'Content-Type: application/json' \ + --data '{"ttl":100}' +``` +```go +package main + +import ( + "context" + "fmt" + "os" + apivideosdk "github.com/apivideo/api.video-go-client" +) + +func main() { + client := apivideosdk.ClientBuilder("YOUR_API_TOKEN").Build() + // if you rather like to use the sandbox environment: + // client := apivideosdk.SandboxClientBuilder("YOU_SANDBOX_API_TOKEN").Build() + + tokenCreationPayload := *apivideosdk.NewTokenCreationPayload() // TokenCreationPayload | + + + res, err := client.UploadTokens.CreateToken(tokenCreationPayload) + + if err != nil { + fmt.Fprintf(os.Stderr, "Error when calling `UploadTokens.CreateToken``: %v\n", err) + } + // response from `CreateToken`: UploadToken + fmt.Fprintf(os.Stdout, "Response from `UploadTokens.CreateToken`: %v\n", res) +} +``` +```php +setTtl(0); +$tokens = $client->uploadTokens()->createToken($payload); + +print($tokens); +``` +```javascript +const ApiVideoClient = require('@api.video/nodejs-client'); + +(async () => { + try { + const client = new ApiVideoClient({ apiKey: "YOUR_API_TOKEN" }); + + const tokenCreationPayload = { + ttl: 56, // Time in seconds that the token will be active. A value of 0 means that the token has no exipration date. The default is to have no expiration. + }; + + // UploadToken + const result = await client.uploadTokens.createToken(tokenCreationPayload); + console.log(result); + } catch (e) { + console.error(e); + } +})(); +``` +```python +## Create a token for use with delegate uploads +import apivideo +from apivideo.apis import UploadTokensApi +from apivideo.exceptions import ApiAuthException + +api_key = "your api key here" + +client = apivideo.AuthenticatedApiClient(api_key) + +## If you'd rather use the sandbox environment: +## client = apivideo.AuthenticatedApiClient(api_key, production=False) + +client.connect() + +## List the time to live (ttl) in seconds for the token you create. +token_creation_payload = {"ttl": 1000} + +tokens_api = UploadTokensApi(client) + +## Create the token +response = tokens_api.create_token(token_creation_payload) +print(response) +``` + +{% endcapture %} +{% include "_partials/code-tabs.html" content: samples %} + +## Upload a video with delegated tokens + +{% capture content %} +If you do a progressive upload with a delegated token, you have to include the video ID you are uploading to after it comes back from the first request. If the video you're uploading is under 200 MiB, you don't need to worry. +{% endcapture %} +{% include "_partials/callout.html" kind: "info", content: content %} + +You must first create a token and get the unique token ID to do a delegated upload. Then, you include it in your request as a query parameter. In the body, you place the path to the file you want to upload. If you are uploading a file that's 200 MiB or larger, to do a progressive upload, you will need to break the file into smaller pieces (no smaller than 5 MiB). Then send a request containing the first piece of your upload. Subsequent pieces must be sent with the video ID included in the body along with the file chunk. Retrieve the video ID from the response that comes back after your first request to upload. + +{% capture samples %} + +```curl +curl --request POST \ + --url 'https://ws.api.video/upload?token=__TOKENIDHERE__' \ + --header 'Accept: application/json' \ + --header 'Content-Type: multipart/form-data' \ + --form file=@FILEPATH.mp4 +``` +```go +package main + +import ( + "context" + "fmt" + "os" + apivideosdk "github.com/apivideo/api.video-go-client" +) + +func main() { + client := apivideosdk.ClientBuilder("YOUR_API_TOKEN").Build() + // if you rather like to use the sandbox environment: + // client := apivideosdk.SandboxClientBuilder("YOU_SANDBOX_API_TOKEN").Build() + + token := "to1tcmSFHeYY5KzyhOqVKMKb" // string | The unique identifier for the token you want to use to upload a video. + file := os.NewFile(1234, "some_file") // *os.File | The path to the video you want to upload. + + + res, err := client.Videos.UploadWithUploadTokenFile(token, file) + + // you can also use a Reader instead of a File: + // client.Videos.UploadWithUploadToken(token, fileName, fileReader, fileSize) + + if err != nil { + fmt.Fprintf(os.Stderr, "Error when calling `Videos.UploadWithUploadToken``: %v\n", err) + } + // response from `UploadWithUploadToken`: Video + fmt.Fprintf(os.Stdout, "Response from `Videos.UploadWithUploadToken`: %v\n", res) +} +``` +```php +use Symfony\Component\HttpClient\Psr18Client; +use ApiVideo\Client\Client; +use ApiVideo\Client\Model\VideosApi; +use ApiVideo\Client\Model\UploadTokensApi; +$apiKey = 'your API key here'; +$apiVideoEndpoint = 'https://ws.api.video'; + +$httpClient = new \Symfony\Component\HttpClient\Psr18Client(); +$client = new ApiVideo\Client\Client( + $apiVideoEndpoint, + $apiKey, + $httpClient +); + +$videos = $client->videos()->upLoadWithUploadToken('token here', new SplFileObject('small_vid.mp4') ); +``` +```javascript +const ApiVideoClient = require('@api.video/nodejs-client'); + +(async () => { + try { + const apiVideoClient = new ApiVideoClient({ apiKey: "YOUR_API_TOKEN" }); + + const token = 'to1tcmSFHeYY5KzyhOqVKMKb'; // The unique identifier for the token you want to use to upload a video. + const file = 'BINARY_DATA_HERE'; // The path to the video you want to upload. + + // Video + const result = await client.videos.uploadWithUploadToken(token, file); + console.log(result); + } catch (e) { + console.error(e); + } +})(); +``` +```python +## Use a delegated token to upload a video +import apivideo +from apivideo.apis import VideosApi +from apivideo.exceptions import ApiAuthException + +api_key = "your api key here" + +client = apivideo.AuthenticatedApiClient(api_key) + +## If you'd rather use the sandbox environment: +## client = apivideo.AuthenticatedApiClient(api_key, production=False) + +client.connect() +videos_api = VideosApi(client) + +## Setting up variables for the path to the video and the token you already created +path = 'path to video' +token = 'your token' + +## Opening your vieo file so it can be sent +file = open(path, "rb") + +## Sending file. +response = videos_api.upload_with_upload_token(token, file) +print(response) +© 2022 GitHub, Inc. +``` +{% endcapture %} +{% include "_partials/code-tabs.html" content: samples %} + +# Token operations + +## List all tokens you created + +If a token is compromised, or you want to see how many tokens you have, you will need to retrieve a list of them programmatically. Here is the code sample for that: + +{% capture samples %} + +```curl +curl --request GET \ + --url 'https://ws.api.video/upload-tokens?currentPage=1&pageSize=25' \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MTQxNDUuMjE2Mzc2LCJuYmYiOjE2NDI4MTQxNDUuMjE2Mzc2LCJleHAiOjE2NDI4MTc3NDUuMjE2Mzc2LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.GSDqqMzBxo-wOwl9IVbOnzevm8A6LSyaR5kxCWUdkEneSU0kIdoNfhwmXZBq5QWpVa-0GIT8JR59W6npNO-ayhaXmV3LA6EQpvv0mHd_dAhg3N8T96eC0ps0YIrkmw0_Oe6iRgEDI-wJ9nc6tQWi9ybbMHi1LDBjxW4rbFlq7G59C1QZGabd14QO7uqAUUSNqHC1l42z_m7BTK1AhFiBEXmMcfW7X0VmGcaEUy7NiNda8rmq_nrdvkxgN8KHguXzxMsw_4GE_d0eQwHcZvS1q-FebI6b8AoqpoltFOZvUACCrfXH_D_UPshHuJM3apXbD2dg_zQicc8oWBHVGiobLQ' +``` +```go +package main + +import ( + "context" + "fmt" + "os" + apivideosdk "github.com/apivideo/api.video-go-client" +) + +func main() { + client := apivideosdk.ClientBuilder("YOUR_API_TOKEN").Build() + // if you rather like to use the sandbox environment: + // client := apivideosdk.SandboxClientBuilder("YOU_SANDBOX_API_TOKEN").Build() + req := apivideosdk.UploadTokensApiListRequest{} + + req.SortBy("ttl") // string | Allowed: createdAt, ttl. You can use these to sort by when a token was created, or how much longer the token will be active (ttl - time to live). Date and time is presented in ISO-8601 format. + req.SortOrder("asc") // string | Allowed: asc, desc. Ascending is 0-9 or A-Z. Descending is 9-0 or Z-A. + req.CurrentPage(int32(2)) // int32 | Choose the number of search results to return per page. Minimum value: 1 (default to 1) + req.PageSize(int32(30)) // int32 | Results per page. Allowed values 1-100, default is 25. (default to 25) + + res, err := client.UploadTokens.List(req) + + + if err != nil { + fmt.Fprintf(os.Stderr, "Error when calling `UploadTokens.List``: %v\n", err) + } + // response from `List`: TokenListResponse + fmt.Fprintf(os.Stdout, "Response from `UploadTokens.List`: %v\n", res) +} +``` +```php +uploadTokens()->list(); + +print($tokens); +``` +```javascript +const ApiVideoClient = require('@api.video/nodejs-client'); + +(async () => { + try { + const client = new ApiVideoClient({ apiKey: "YOUR_API_TOKEN" }); + + const sortBy = 'ttl'; // Allowed: createdAt, ttl. You can use these to sort by when a token was created, or how much longer the token will be active (ttl - time to live). Date and time is presented in ISO-8601 format. + const sortOrder = 'asc'; // Allowed: asc, desc. Ascending is 0-9 or A-Z. Descending is 9-0 or Z-A. + const currentPage = '2'; // Choose the number of search results to return per page. Minimum value: 1 + const pageSize = '30'; // Results per page. Allowed values 1-100, default is 25. + + // TokenListResponse + const result = await client.uploadTokens.list({ sortBy, sortOrder, currentPage, pageSize }) + console.log(result); + } catch (e) { + console.error(e); + } +})(); +``` +```python +## List all delegated tokens that are active +import apivideo +from apivideo.apis import UploadTokensApi +from apivideo.exceptions import ApiAuthException + +api_key = "your api key here" + +client = apivideo.AuthenticatedApiClient(api_key) + +## If you'd rather use the sandbox environment: +## client = apivideo.AuthenticatedApiClient(api_key, production=False) + +client.connect() + +tokens_api = UploadTokensApi(client) + +## List all delegated tokens +response = tokens_api.list() +print(response) +``` + +{% endcapture %} +{% include "_partials/code-tabs.html" content: samples %} + + +## Show details about a specific token + +Retrieve information about a specific token. To do this, you send a request containing the token ID for the token you need details about. + +{% capture samples %} + +```curl +curl --request GET \ + --url https://ws.api.video/upload-tokens/to40nBwUZJGnuW8THBZwPqtL \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MTQxNDUuMjE2Mzc2LCJuYmYiOjE2NDI4MTQxNDUuMjE2Mzc2LCJleHAiOjE2NDI4MTc3NDUuMjE2Mzc2LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.GSDqqMzBxo-wOwl9IVbOnzevm8A6LSyaR5kxCWUdkEneSU0kIdoNfhwmXZBq5QWpVa-0GIT8JR59W6npNO-ayhaXmV3LA6EQpvv0mHd_dAhg3N8T96eC0ps0YIrkmw0_Oe6iRgEDI-wJ9nc6tQWi9ybbMHi1LDBjxW4rbFlq7G59C1QZGabd14QO7uqAUUSNqHC1l42z_m7BTK1AhFiBEXmMcfW7X0VmGcaEUy7NiNda8rmq_nrdvkxgN8KHguXzxMsw_4GE_d0eQwHcZvS1q-FebI6b8AoqpoltFOZvUACCrfXH_D_UPshHuJM3apXbD2dg_zQicc8oWBHVGiobLQ' +``` +```go +package main + +import ( + "context" + "fmt" + "os" + apivideosdk "github.com/apivideo/api.video-go-client" +) + +func main() { + client := apivideosdk.ClientBuilder("YOUR_API_TOKEN").Build() + // if you rather like to use the sandbox environment: + // client := apivideosdk.SandboxClientBuilder("YOU_SANDBOX_API_TOKEN").Build() + + uploadToken := "to1tcmSFHeYY5KzyhOqVKMKb" // string | The unique identifier for the token you want information about. + + + res, err := client.UploadTokens.GetToken(uploadToken) + + if err != nil { + fmt.Fprintf(os.Stderr, "Error when calling `UploadTokens.GetToken``: %v\n", err) + } + // response from `GetToken`: UploadToken + fmt.Fprintf(os.Stdout, "Response from `UploadTokens.GetToken`: %v\n", res) +} +``` +```php +uploadTokens()->getToken('token here'); + +print($tokens); +``` +```javascript +const ApiVideoClient = require('@api.video/nodejs-client'); + +(async () => { + try { + const client = new ApiVideoClient({ apiKey: "YOUR_API_TOKEN" }); + + const uploadToken = 'to1tcmSFHeYY5KzyhOqVKMKb'; // The unique identifier for the token you want information about. + + // UploadToken + const result = await client.uploadTokens.getToken(uploadToken); + console.log(result); + } catch (e) { + console.error(e); + } +})(); +``` +```python +## Get information about a single token using the token ID +import apivideo +from apivideo.apis import UploadTokensApi +from apivideo.exceptions import ApiAuthException + +## Set variables +api_key = "your api key here" +token = "your token ID here" + +## Set up the client +client = apivideo.AuthenticatedApiClient(api_key) + +## If you'd rather use the sandbox environment: +## client = apivideo.AuthenticatedApiClient(api_key, production=False) + +client.connect() + +tokens_api = UploadTokensApi(client) + +## Send your request to retrieve information about a specific token +response = tokens_api.get_token(token) +print(response) +``` + +{% endcapture %} +{% include "_partials/code-tabs.html" content: samples %} + + +## Delete a token + +If you create a token that's compromised, you may want to remove it. Or, you might want to clean up how many tokens you have in general. All you need to do to delete a token is send a request containing the token ID for the token you want to remove. + +{% capture samples %} + +```curl +curl --request DELETE \ + --url https://ws.api.video/upload-tokens/curl%20--request%20GET%20%5C%20%20%20%20%20%20--url%20https%3A%2F%2Fws.api.video%2Fupload-tokens%2Fto40nBwUZJGnuW8THBZwPqtL%20%5C%20%20%20%20%20%20--header%20%27Accept%3A%20application%2Fjson%27%20%5C%20%20%20%20%20%20--header%20%27Authorization%3A%20Bearer%20eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MTQxNDUuMjE2Mzc2LCJuYmYiOjE2NDI4MTQxNDUuMjE2Mzc2LCJleHAiOjE2NDI4MTc3NDUuMjE2Mzc2LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.GSDqqMzBxo-wOwl9IVbOnzevm8A6LSyaR5kxCWUdkEneSU0kIdoNfhwmXZBq5QWpVa-0GIT8JR59W6npNO-ayhaXmV3LA6EQpvv0mHd_dAhg3N8T96eC0ps0YIrkmw0_Oe6iRgEDI-wJ9nc6tQWi9ybbMHi1LDBjxW4rbFlq7G59C1QZGabd14QO7uqAUUSNqHC1l42z_m7BTK1AhFiBEXmMcfW7X0VmGcaEUy7NiNda8rmq_nrdvkxgN8KHguXzxMsw_4GE_d0eQwHcZvS1q-FebI6b8AoqpoltFOZvUACCrfXH_D_UPshHuJM3apXbD2dg_zQicc8oWBHVGiobLQ%27 \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MTQxNDUuMjE2Mzc2LCJuYmYiOjE2NDI4MTQxNDUuMjE2Mzc2LCJleHAiOjE2NDI4MTc3NDUuMjE2Mzc2LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.GSDqqMzBxo-wOwl9IVbOnzevm8A6LSyaR5kxCWUdkEneSU0kIdoNfhwmXZBq5QWpVa-0GIT8JR59W6npNO-ayhaXmV3LA6EQpvv0mHd_dAhg3N8T96eC0ps0YIrkmw0_Oe6iRgEDI-wJ9nc6tQWi9ybbMHi1LDBjxW4rbFlq7G59C1QZGabd14QO7uqAUUSNqHC1l42z_m7BTK1AhFiBEXmMcfW7X0VmGcaEUy7NiNda8rmq_nrdvkxgN8KHguXzxMsw_4GE_d0eQwHcZvS1q-FebI6b8AoqpoltFOZvUACCrfXH_D_UPshHuJM3apXbD2dg_zQicc8oWBHVGiobLQ' +``` +```go +package main + +import ( + "context" + "fmt" + "os" + apivideosdk "github.com/apivideo/api.video-go-client" +) + +func main() { + client := apivideosdk.ClientBuilder("YOUR_API_TOKEN").Build() + // if you rather like to use the sandbox environment: + // client := apivideosdk.SandboxClientBuilder("YOU_SANDBOX_API_TOKEN").Build() + + uploadToken := "to1tcmSFHeYY5KzyhOqVKMKb" // string | The unique identifier for the upload token you want to delete. Deleting a token will make it so the token can no longer be used for authentication. + + + err := client.UploadTokens.DeleteToken(uploadToken) + + if err != nil { + fmt.Fprintf(os.Stderr, "Error when calling `UploadTokens.DeleteToken``: %v\n", err) + } +} +``` +```php +uploadTokens()->deleteToken('token here'); + +print($tokens); +``` +```javascript +const ApiVideoClient = require('@api.video/nodejs-client'); + +(async () => { + try { + const client = new ApiVideoClient({ apiKey: "YOUR_API_TOKEN" }); + + const uploadToken = 'to1tcmSFHeYY5KzyhOqVKMKb'; // The unique identifier for the upload token you want to delete. Deleting a token will make it so the token can no longer be used for authentication. + + // void + const result = await client.uploadTokens.deleteToken(uploadToken); + console.log(result); + } catch (e) { + console.error(e); + } +})(); +``` +```python +## Delete a video using its video ID +import apivideo +from apivideo.apis import VideosApi +from apivideo.exceptions import ApiAuthException + +api_key = "your api key here" + +client = apivideo.AuthenticatedApiClient(api_key) + +## If you'd rather use the sandbox environment: +## client = apivideo.AuthenticatedApiClient(api_key, production=False) + +client.connect() + +videos_api = VideosApi(client) + +title = "Sample AVI Video" + +## List videos that have the exact, unique title you wanted to delete +videos = videos_api.list(title=title) + +## Get list of videos out of response object or single item depending on whether you filtered +videos = videos['data'] + +## In this case, let's assume we know there's only one video with the title we filtered for. +print(videos[0]['video_id']) + +## Delete the video +response = videos_api.delete(videos[0]['video_id']) +print(response) +``` + +{% endcapture %} +{% include "_partials/code-tabs.html" content: samples %} + + +## Conclusion + +Delegated upload is a useful method if you want to allow users to upload videos - you can provide them delegated upload tokans that expire. You can also use this method to create one-time video uploader solutions. It's also useful if you want to upload content quickly without worrying about the metadata. Everything is uploaded at once - it's just the video and the title. You can add the metadata later. \ No newline at end of file diff --git a/get-started/using-tokens.md b/get-started/using-tokens.md index 19562975..8560e50f 100644 --- a/get-started/using-tokens.md +++ b/get-started/using-tokens.md @@ -1,25 +1,32 @@ -api.video provides you with various options of authentication which allows you to leverage the API on a different level of your application, whether it's on the front end or backend. Moreover, you can provide better security for your backend and videos. +--- +title: "Using tokens" +slug: "using-tokens" +meta: + description: This page explains the various options of authentication using access tokens, refresh tokens, delegated upload tokens, private tokens, and session tokens. +--- -# Upload & API Access Tokens +api.video provides you with various options of authentication that enable you to leverage the API on different levels of your application, whether it's on the frontend or the backend. Moreover, you can provide better security for your backend and videos using delegated upload tokens. -## Access Token +# API access & upload tokens -This token is created to enhance the backend security and create a short-lived bearer token that will replace your API key for any API request. The Access Token is a disposable bearer token that is being generated from the [/auth/api-key](https://docs.api.video/reference/post_auth-api-key) endpoint, by passing the workspace API key. The endpoint will respond with a short-lived bearer token (3600 seconds) that can be refreshed by making a request to the [/auth/refresh](https://docs.api.video/reference/post_auth-refresh) endpoint. +## Access tokens -For more detailed information, head over to [the article about the Access Token](https://docs.api.video/reference/disposable-bearer-token-authentication) +This token is created to enhance the backend security and create a short-lived bearer token that will replace your API key for any API request. The Access Token is a disposable bearer token that is being generated from the [/auth/api-key](/reference/api/Advanced-authentication#get-bearer-token) endpoint, by passing the workspace API key. The endpoint will respond with a short-lived bearer token (3600 seconds) that can be refreshed by making a request to the [/auth/refresh](/reference/api/Advanced-authentication#refresh-bearer-token) endpoint. -## Delegated Upload Token +For more detailed information, head over to [the article about the Access Token](/reference/disposable-bearer-token-authentication.md) + +## Delegated upload tokens The delegated upload token is created in order to assist you in building features in the front end. The delegated upload token is a one-time token that is valid only with the [/upload](https://docs.api.video/reference/post_upload) endpoint. The idea behind it is that you can serve a one-time token to the front end from the back end that will be used by the front-end to upload a video. For more details please visit the [Delegated upload tokens page](https://docs.api.video/reference/upload-tokens). -# Video Access Management Tokens +# Video access management tokens -## Private Token +## Private tokens In order for your user to consume private videos, api.video will generate a one-time private token for the assets to be passed as a query parameter. You can learn more about private videos and private tokens [here](https://docs.api.video/docs/private-videos). -## Session Token +## Session tokens This token's purpose is to retain a private session for private videos. When you serve private videos to your user, you will have to leverage session tokens to retrain the session and continue consuming other assets that are related to the video. Learn more about session tokens [here](https://docs.api.video/docs/private-video-session-tokens). \ No newline at end of file diff --git a/navigation.yaml b/navigation.yaml index f624dd9f..d84f30b1 100644 --- a/navigation.yaml +++ b/navigation.yaml @@ -14,15 +14,13 @@ href: /get-started/azure-migration.md - label: AWS href: /get-started/aws-migration.md - - label: Authentication - href: /get-started/authentication-guide.md - label: Using tokens href: /get-started/using-tokens.md collapsed: true items: - - label: Create and manage delegated upload tokens - href: /get-started/create-and-manage-tokens-for-delegated-uploads.md - - label: Upload a video with a delegated token - href: /get-started/upload-a-video-with-a-delegated-token.md + - label: Authentication and refresh tokens + href: /get-started/authentication-guide.md + - label: Delegated upload tokens + href: /get-started/delegated-upload-tokens.md - label: SDK Catalog href: /sdks/README.md \ No newline at end of file diff --git a/vod/delegated-upload-tokens.md b/vod/delegated-upload-tokens.md new file mode 100644 index 00000000..028b8e57 --- /dev/null +++ b/vod/delegated-upload-tokens.md @@ -0,0 +1,649 @@ +--- +title: "Delegated upload tokens" +slug: "delegated-upload-tokens" +metadata: + description: This guide explains how to create, list, retrieve, and delete delegated upload tokens, and how to upload videos with them. +--- + +Using delegated upload tokens +============================================== + +You can upload videos using the traditional two-step process where you create a video container then upload your video into your container. You can also upload a video using a **delegated upload token**. This guide explains how to create, list, retrieve, and delete delegated upload tokens, and how to upload videos with them. + +In this type of upload, you retrieve a token from the tokens endpoint. You can then directly upload using the token upload endpoint. It's one step, and you don't provide anything except the file. You can update the metadata for the upload later. A benefit of a delegated token is that you define the TTL (time-to-live) value, so it expires only when you need it to. You can always use the token to upload. You can also create delegated tokens for others to use to do uploads. + +* Anyone who has a token can make an upload, so be careful how you set and manage tokens. +* You can create as many tokens as you need. +* If you do not include a TTL (time-to-live) value for a token, it lasts until you delete it. + +{% capture content %} +If you want to learn about regular or progressive uploads, check out the [Upload a video - regular, progressive, and bytes](/vod/upload-a-video-regular-upload) guide. +{% endcapture %} +{% include "_partials/callout.html" kind: "info", content: content %} + +## API documentation + +- [Upload Tokens](/reference/api/Upload-Tokens) +- [Upload with an upload token](/reference/api/Videos#upload-with-an-delegated-upload-token) + +## Resources + +We offer blog content on this topic: + +- [Delegated uploads](https://api.video/blog/tutorials/delegated-uploads) - **cURL** Walk through how to do a delegated upload using cURL. +- [Delegated uploads for videos large and small](https://api.video/blog/tutorials/delegated-uploads-for-videos-large-and-small-python) - **Python** Learn how to do a delegated upload using Python. + +## Create an account + +Before you can start uploading your first video, you need to [create an api.video account](https://dashboard.api.video/register). + +Once you are logged in to the Dashboard, select the environment of your choice (sandbox or production) and copy your API key. + +![](/_assets/retrieve-api-key.png) + +## Choose an api.video client + +The clients offered by api.video include: + +- [NodeJS](/sdks/api-clients/apivideo-nodejs-client.md) +- [Python](/sdks/api-clients/apivideo-python-client.md) +- [PHP](/sdks/api-clients/apivideo-php-client.md) +- [Go](/sdks/api-clients/apivideo-go-client.md) +- [C#](/sdks/api-clients/apivideo-csharp-client.md) +- [Java](/sdks/api-clients/apivideo-java-client.md) +- [iOS](/sdks/api-clients/ios-api-client.md) +- [Android](/sdks/api-clients/android-api-client.md) + +## Installation + +To install your selected client, do the following: + +{% capture samples %} + +```go +go get github.com/apivideo/api.video-go-client +``` +```php +composer require api-video/php-api-client +``` +```javascript +npm install @api.video/nodejs-client --save + +...or with yarn: + +yarn add @api.video/nodejs-client +``` +```python +pip install api.video +``` +```csharp +Using Nuget + +Install-Package ApiVideo +``` + +{% endcapture %} +{% include "_partials/code-tabs.html" content: samples %} + +## Generate a token for delegated upload + +Use this code sample to generate a token for use with a delegated upload. You can include a TTL (time-to-live) if you like. The token will expire after exceeding the set TTL. If you don't send in a TTL, your token will last until you choose to delete it. + +{% capture samples %} + +```curl +curl --request POST \ + --url https://ws.api.video/upload-tokens \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MTQxNDUuMjE2Mzc2LCJuYmYiOjE2NDI4MTQxNDUuMjE2Mzc2LCJleHAiOjE2NDI4MTc3NDUuMjE2Mzc2LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.GSDqqMzBxo-wOwl9IVbOnzevm8A6LSyaR5kxCWUdkEneSU0kIdoNfhwmXZBq5QWpVa-0GIT8JR59W6npNO-ayhaXmV3LA6EQpvv0mHd_dAhg3N8T96eC0ps0YIrkmw0_Oe6iRgEDI-wJ9nc6tQWi9ybbMHi1LDBjxW4rbFlq7G59C1QZGabd14QO7uqAUUSNqHC1l42z_m7BTK1AhFiBEXmMcfW7X0VmGcaEUy7NiNda8rmq_nrdvkxgN8KHguXzxMsw_4GE_d0eQwHcZvS1q-FebI6b8AoqpoltFOZvUACCrfXH_D_UPshHuJM3apXbD2dg_zQicc8oWBHVGiobLQ' \ + --header 'Content-Type: application/json' \ + --data '{"ttl":100}' +``` +```go +package main + +import ( + "context" + "fmt" + "os" + apivideosdk "github.com/apivideo/api.video-go-client" +) + +func main() { + client := apivideosdk.ClientBuilder("YOUR_API_TOKEN").Build() + // if you rather like to use the sandbox environment: + // client := apivideosdk.SandboxClientBuilder("YOU_SANDBOX_API_TOKEN").Build() + + tokenCreationPayload := *apivideosdk.NewTokenCreationPayload() // TokenCreationPayload | + + + res, err := client.UploadTokens.CreateToken(tokenCreationPayload) + + if err != nil { + fmt.Fprintf(os.Stderr, "Error when calling `UploadTokens.CreateToken``: %v\n", err) + } + // response from `CreateToken`: UploadToken + fmt.Fprintf(os.Stdout, "Response from `UploadTokens.CreateToken`: %v\n", res) +} +``` +```php +setTtl(0); +$tokens = $client->uploadTokens()->createToken($payload); + +print($tokens); +``` +```javascript +const ApiVideoClient = require('@api.video/nodejs-client'); + +(async () => { + try { + const client = new ApiVideoClient({ apiKey: "YOUR_API_TOKEN" }); + + const tokenCreationPayload = { + ttl: 56, // Time in seconds that the token will be active. A value of 0 means that the token has no exipration date. The default is to have no expiration. + }; + + // UploadToken + const result = await client.uploadTokens.createToken(tokenCreationPayload); + console.log(result); + } catch (e) { + console.error(e); + } +})(); +``` +```python +## Create a token for use with delegate uploads +import apivideo +from apivideo.apis import UploadTokensApi +from apivideo.exceptions import ApiAuthException + +api_key = "your api key here" + +client = apivideo.AuthenticatedApiClient(api_key) + +## If you'd rather use the sandbox environment: +## client = apivideo.AuthenticatedApiClient(api_key, production=False) + +client.connect() + +## List the time to live (ttl) in seconds for the token you create. +token_creation_payload = {"ttl": 1000} + +tokens_api = UploadTokensApi(client) + +## Create the token +response = tokens_api.create_token(token_creation_payload) +print(response) +``` + +{% endcapture %} +{% include "_partials/code-tabs.html" content: samples %} + +## Upload a video with delegated tokens + +{% capture content %} +If you do a progressive upload with a delegated token, you have to include the video ID you are uploading to after it comes back from the first request. If the video you're uploading is under 200 MiB, you don't need to worry. +{% endcapture %} +{% include "_partials/callout.html" kind: "info", content: content %} + +You must first create a token and get the unique token ID to do a delegated upload. Then, you include it in your request as a query parameter. In the body, you place the path to the file you want to upload. If you are uploading a file that's 200 MiB or larger, to do a progressive upload, you will need to break the file into smaller pieces (no smaller than 5 MiB). Then send a request containing the first piece of your upload. Subsequent pieces must be sent with the video ID included in the body along with the file chunk. Retrieve the video ID from the response that comes back after your first request to upload. + +{% capture samples %} + +```curl +curl --request POST \ + --url 'https://ws.api.video/upload?token=__TOKENIDHERE__' \ + --header 'Accept: application/json' \ + --header 'Content-Type: multipart/form-data' \ + --form file=@FILEPATH.mp4 +``` +```go +package main + +import ( + "context" + "fmt" + "os" + apivideosdk "github.com/apivideo/api.video-go-client" +) + +func main() { + client := apivideosdk.ClientBuilder("YOUR_API_TOKEN").Build() + // if you rather like to use the sandbox environment: + // client := apivideosdk.SandboxClientBuilder("YOU_SANDBOX_API_TOKEN").Build() + + token := "to1tcmSFHeYY5KzyhOqVKMKb" // string | The unique identifier for the token you want to use to upload a video. + file := os.NewFile(1234, "some_file") // *os.File | The path to the video you want to upload. + + + res, err := client.Videos.UploadWithUploadTokenFile(token, file) + + // you can also use a Reader instead of a File: + // client.Videos.UploadWithUploadToken(token, fileName, fileReader, fileSize) + + if err != nil { + fmt.Fprintf(os.Stderr, "Error when calling `Videos.UploadWithUploadToken``: %v\n", err) + } + // response from `UploadWithUploadToken`: Video + fmt.Fprintf(os.Stdout, "Response from `Videos.UploadWithUploadToken`: %v\n", res) +} +``` +```php +use Symfony\Component\HttpClient\Psr18Client; +use ApiVideo\Client\Client; +use ApiVideo\Client\Model\VideosApi; +use ApiVideo\Client\Model\UploadTokensApi; +$apiKey = 'your API key here'; +$apiVideoEndpoint = 'https://ws.api.video'; + +$httpClient = new \Symfony\Component\HttpClient\Psr18Client(); +$client = new ApiVideo\Client\Client( + $apiVideoEndpoint, + $apiKey, + $httpClient +); + +$videos = $client->videos()->upLoadWithUploadToken('token here', new SplFileObject('small_vid.mp4') ); +``` +```javascript +const ApiVideoClient = require('@api.video/nodejs-client'); + +(async () => { + try { + const apiVideoClient = new ApiVideoClient({ apiKey: "YOUR_API_TOKEN" }); + + const token = 'to1tcmSFHeYY5KzyhOqVKMKb'; // The unique identifier for the token you want to use to upload a video. + const file = 'BINARY_DATA_HERE'; // The path to the video you want to upload. + + // Video + const result = await client.videos.uploadWithUploadToken(token, file); + console.log(result); + } catch (e) { + console.error(e); + } +})(); +``` +```python +## Use a delegated token to upload a video +import apivideo +from apivideo.apis import VideosApi +from apivideo.exceptions import ApiAuthException + +api_key = "your api key here" + +client = apivideo.AuthenticatedApiClient(api_key) + +## If you'd rather use the sandbox environment: +## client = apivideo.AuthenticatedApiClient(api_key, production=False) + +client.connect() +videos_api = VideosApi(client) + +## Setting up variables for the path to the video and the token you already created +path = 'path to video' +token = 'your token' + +## Opening your vieo file so it can be sent +file = open(path, "rb") + +## Sending file. +response = videos_api.upload_with_upload_token(token, file) +print(response) +© 2022 GitHub, Inc. +``` +{% endcapture %} +{% include "_partials/code-tabs.html" content: samples %} + +# Token operations + +## List all tokens you created + +If a token is compromised, or you want to see how many tokens you have, you will need to retrieve a list of them programmatically. Here is the code sample for that: + +{% capture samples %} + +```curl +curl --request GET \ + --url 'https://ws.api.video/upload-tokens?currentPage=1&pageSize=25' \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MTQxNDUuMjE2Mzc2LCJuYmYiOjE2NDI4MTQxNDUuMjE2Mzc2LCJleHAiOjE2NDI4MTc3NDUuMjE2Mzc2LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.GSDqqMzBxo-wOwl9IVbOnzevm8A6LSyaR5kxCWUdkEneSU0kIdoNfhwmXZBq5QWpVa-0GIT8JR59W6npNO-ayhaXmV3LA6EQpvv0mHd_dAhg3N8T96eC0ps0YIrkmw0_Oe6iRgEDI-wJ9nc6tQWi9ybbMHi1LDBjxW4rbFlq7G59C1QZGabd14QO7uqAUUSNqHC1l42z_m7BTK1AhFiBEXmMcfW7X0VmGcaEUy7NiNda8rmq_nrdvkxgN8KHguXzxMsw_4GE_d0eQwHcZvS1q-FebI6b8AoqpoltFOZvUACCrfXH_D_UPshHuJM3apXbD2dg_zQicc8oWBHVGiobLQ' +``` +```go +package main + +import ( + "context" + "fmt" + "os" + apivideosdk "github.com/apivideo/api.video-go-client" +) + +func main() { + client := apivideosdk.ClientBuilder("YOUR_API_TOKEN").Build() + // if you rather like to use the sandbox environment: + // client := apivideosdk.SandboxClientBuilder("YOU_SANDBOX_API_TOKEN").Build() + req := apivideosdk.UploadTokensApiListRequest{} + + req.SortBy("ttl") // string | Allowed: createdAt, ttl. You can use these to sort by when a token was created, or how much longer the token will be active (ttl - time to live). Date and time is presented in ISO-8601 format. + req.SortOrder("asc") // string | Allowed: asc, desc. Ascending is 0-9 or A-Z. Descending is 9-0 or Z-A. + req.CurrentPage(int32(2)) // int32 | Choose the number of search results to return per page. Minimum value: 1 (default to 1) + req.PageSize(int32(30)) // int32 | Results per page. Allowed values 1-100, default is 25. (default to 25) + + res, err := client.UploadTokens.List(req) + + + if err != nil { + fmt.Fprintf(os.Stderr, "Error when calling `UploadTokens.List``: %v\n", err) + } + // response from `List`: TokenListResponse + fmt.Fprintf(os.Stdout, "Response from `UploadTokens.List`: %v\n", res) +} +``` +```php +uploadTokens()->list(); + +print($tokens); +``` +```javascript +const ApiVideoClient = require('@api.video/nodejs-client'); + +(async () => { + try { + const client = new ApiVideoClient({ apiKey: "YOUR_API_TOKEN" }); + + const sortBy = 'ttl'; // Allowed: createdAt, ttl. You can use these to sort by when a token was created, or how much longer the token will be active (ttl - time to live). Date and time is presented in ISO-8601 format. + const sortOrder = 'asc'; // Allowed: asc, desc. Ascending is 0-9 or A-Z. Descending is 9-0 or Z-A. + const currentPage = '2'; // Choose the number of search results to return per page. Minimum value: 1 + const pageSize = '30'; // Results per page. Allowed values 1-100, default is 25. + + // TokenListResponse + const result = await client.uploadTokens.list({ sortBy, sortOrder, currentPage, pageSize }) + console.log(result); + } catch (e) { + console.error(e); + } +})(); +``` +```python +## List all delegated tokens that are active +import apivideo +from apivideo.apis import UploadTokensApi +from apivideo.exceptions import ApiAuthException + +api_key = "your api key here" + +client = apivideo.AuthenticatedApiClient(api_key) + +## If you'd rather use the sandbox environment: +## client = apivideo.AuthenticatedApiClient(api_key, production=False) + +client.connect() + +tokens_api = UploadTokensApi(client) + +## List all delegated tokens +response = tokens_api.list() +print(response) +``` + +{% endcapture %} +{% include "_partials/code-tabs.html" content: samples %} + + +## Show details about a specific token + +Retrieve information about a specific token. To do this, you send a request containing the token ID for the token you need details about. + +{% capture samples %} + +```curl +curl --request GET \ + --url https://ws.api.video/upload-tokens/to40nBwUZJGnuW8THBZwPqtL \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MTQxNDUuMjE2Mzc2LCJuYmYiOjE2NDI4MTQxNDUuMjE2Mzc2LCJleHAiOjE2NDI4MTc3NDUuMjE2Mzc2LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.GSDqqMzBxo-wOwl9IVbOnzevm8A6LSyaR5kxCWUdkEneSU0kIdoNfhwmXZBq5QWpVa-0GIT8JR59W6npNO-ayhaXmV3LA6EQpvv0mHd_dAhg3N8T96eC0ps0YIrkmw0_Oe6iRgEDI-wJ9nc6tQWi9ybbMHi1LDBjxW4rbFlq7G59C1QZGabd14QO7uqAUUSNqHC1l42z_m7BTK1AhFiBEXmMcfW7X0VmGcaEUy7NiNda8rmq_nrdvkxgN8KHguXzxMsw_4GE_d0eQwHcZvS1q-FebI6b8AoqpoltFOZvUACCrfXH_D_UPshHuJM3apXbD2dg_zQicc8oWBHVGiobLQ' +``` +```go +package main + +import ( + "context" + "fmt" + "os" + apivideosdk "github.com/apivideo/api.video-go-client" +) + +func main() { + client := apivideosdk.ClientBuilder("YOUR_API_TOKEN").Build() + // if you rather like to use the sandbox environment: + // client := apivideosdk.SandboxClientBuilder("YOU_SANDBOX_API_TOKEN").Build() + + uploadToken := "to1tcmSFHeYY5KzyhOqVKMKb" // string | The unique identifier for the token you want information about. + + + res, err := client.UploadTokens.GetToken(uploadToken) + + if err != nil { + fmt.Fprintf(os.Stderr, "Error when calling `UploadTokens.GetToken``: %v\n", err) + } + // response from `GetToken`: UploadToken + fmt.Fprintf(os.Stdout, "Response from `UploadTokens.GetToken`: %v\n", res) +} +``` +```php +uploadTokens()->getToken('token here'); + +print($tokens); +``` +```javascript +const ApiVideoClient = require('@api.video/nodejs-client'); + +(async () => { + try { + const client = new ApiVideoClient({ apiKey: "YOUR_API_TOKEN" }); + + const uploadToken = 'to1tcmSFHeYY5KzyhOqVKMKb'; // The unique identifier for the token you want information about. + + // UploadToken + const result = await client.uploadTokens.getToken(uploadToken); + console.log(result); + } catch (e) { + console.error(e); + } +})(); +``` +```python +## Get information about a single token using the token ID +import apivideo +from apivideo.apis import UploadTokensApi +from apivideo.exceptions import ApiAuthException + +## Set variables +api_key = "your api key here" +token = "your token ID here" + +## Set up the client +client = apivideo.AuthenticatedApiClient(api_key) + +## If you'd rather use the sandbox environment: +## client = apivideo.AuthenticatedApiClient(api_key, production=False) + +client.connect() + +tokens_api = UploadTokensApi(client) + +## Send your request to retrieve information about a specific token +response = tokens_api.get_token(token) +print(response) +``` + +{% endcapture %} +{% include "_partials/code-tabs.html" content: samples %} + + +## Delete a token + +If you create a token that's compromised, you may want to remove it. Or, you might want to clean up how many tokens you have in general. All you need to do to delete a token is send a request containing the token ID for the token you want to remove. + +{% capture samples %} + +```curl +curl --request DELETE \ + --url https://ws.api.video/upload-tokens/curl%20--request%20GET%20%5C%20%20%20%20%20%20--url%20https%3A%2F%2Fws.api.video%2Fupload-tokens%2Fto40nBwUZJGnuW8THBZwPqtL%20%5C%20%20%20%20%20%20--header%20%27Accept%3A%20application%2Fjson%27%20%5C%20%20%20%20%20%20--header%20%27Authorization%3A%20Bearer%20eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MTQxNDUuMjE2Mzc2LCJuYmYiOjE2NDI4MTQxNDUuMjE2Mzc2LCJleHAiOjE2NDI4MTc3NDUuMjE2Mzc2LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.GSDqqMzBxo-wOwl9IVbOnzevm8A6LSyaR5kxCWUdkEneSU0kIdoNfhwmXZBq5QWpVa-0GIT8JR59W6npNO-ayhaXmV3LA6EQpvv0mHd_dAhg3N8T96eC0ps0YIrkmw0_Oe6iRgEDI-wJ9nc6tQWi9ybbMHi1LDBjxW4rbFlq7G59C1QZGabd14QO7uqAUUSNqHC1l42z_m7BTK1AhFiBEXmMcfW7X0VmGcaEUy7NiNda8rmq_nrdvkxgN8KHguXzxMsw_4GE_d0eQwHcZvS1q-FebI6b8AoqpoltFOZvUACCrfXH_D_UPshHuJM3apXbD2dg_zQicc8oWBHVGiobLQ%27 \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MTQxNDUuMjE2Mzc2LCJuYmYiOjE2NDI4MTQxNDUuMjE2Mzc2LCJleHAiOjE2NDI4MTc3NDUuMjE2Mzc2LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.GSDqqMzBxo-wOwl9IVbOnzevm8A6LSyaR5kxCWUdkEneSU0kIdoNfhwmXZBq5QWpVa-0GIT8JR59W6npNO-ayhaXmV3LA6EQpvv0mHd_dAhg3N8T96eC0ps0YIrkmw0_Oe6iRgEDI-wJ9nc6tQWi9ybbMHi1LDBjxW4rbFlq7G59C1QZGabd14QO7uqAUUSNqHC1l42z_m7BTK1AhFiBEXmMcfW7X0VmGcaEUy7NiNda8rmq_nrdvkxgN8KHguXzxMsw_4GE_d0eQwHcZvS1q-FebI6b8AoqpoltFOZvUACCrfXH_D_UPshHuJM3apXbD2dg_zQicc8oWBHVGiobLQ' +``` +```go +package main + +import ( + "context" + "fmt" + "os" + apivideosdk "github.com/apivideo/api.video-go-client" +) + +func main() { + client := apivideosdk.ClientBuilder("YOUR_API_TOKEN").Build() + // if you rather like to use the sandbox environment: + // client := apivideosdk.SandboxClientBuilder("YOU_SANDBOX_API_TOKEN").Build() + + uploadToken := "to1tcmSFHeYY5KzyhOqVKMKb" // string | The unique identifier for the upload token you want to delete. Deleting a token will make it so the token can no longer be used for authentication. + + + err := client.UploadTokens.DeleteToken(uploadToken) + + if err != nil { + fmt.Fprintf(os.Stderr, "Error when calling `UploadTokens.DeleteToken``: %v\n", err) + } +} +``` +```php +uploadTokens()->deleteToken('token here'); + +print($tokens); +``` +```javascript +const ApiVideoClient = require('@api.video/nodejs-client'); + +(async () => { + try { + const client = new ApiVideoClient({ apiKey: "YOUR_API_TOKEN" }); + + const uploadToken = 'to1tcmSFHeYY5KzyhOqVKMKb'; // The unique identifier for the upload token you want to delete. Deleting a token will make it so the token can no longer be used for authentication. + + // void + const result = await client.uploadTokens.deleteToken(uploadToken); + console.log(result); + } catch (e) { + console.error(e); + } +})(); +``` +```python +## Delete a video using its video ID +import apivideo +from apivideo.apis import VideosApi +from apivideo.exceptions import ApiAuthException + +api_key = "your api key here" + +client = apivideo.AuthenticatedApiClient(api_key) + +## If you'd rather use the sandbox environment: +## client = apivideo.AuthenticatedApiClient(api_key, production=False) + +client.connect() + +videos_api = VideosApi(client) + +title = "Sample AVI Video" + +## List videos that have the exact, unique title you wanted to delete +videos = videos_api.list(title=title) + +## Get list of videos out of response object or single item depending on whether you filtered +videos = videos['data'] + +## In this case, let's assume we know there's only one video with the title we filtered for. +print(videos[0]['video_id']) + +## Delete the video +response = videos_api.delete(videos[0]['video_id']) +print(response) +``` + +{% endcapture %} +{% include "_partials/code-tabs.html" content: samples %} + + +## Conclusion + +Delegated upload is a useful method if you want to allow users to upload videos - you can provide them delegated upload tokans that expire. You can also use this method to create one-time video uploader solutions. It's also useful if you want to upload content quickly without worrying about the metadata. Everything is uploaded at once - it's just the video and the title. You can add the metadata later. \ No newline at end of file diff --git a/vod/navigation.yaml b/vod/navigation.yaml index 01dd384d..f47b9b7a 100644 --- a/vod/navigation.yaml +++ b/vod/navigation.yaml @@ -48,10 +48,8 @@ href: /vod/using-tokens.md collapsed: true items: - - label: Create and manage delegated upload tokens - href: /vod/create-and-manage-tokens-for-delegated-uploads.md - - label: Upload a video with a delegated token - href: /vod/upload-a-video-with-a-delegated-token.md + - label: Delegated upload tokens + href: /vod/delegated-upload-tokens.md - heading: Video management items: diff --git a/vod/using-tokens.md b/vod/using-tokens.md index 7849e4bd..8560e50f 100644 --- a/vod/using-tokens.md +++ b/vod/using-tokens.md @@ -1,33 +1,32 @@ --- -title: "Using upload tokens" +title: "Using tokens" slug: "using-tokens" -metadata: - title: "Using upload tokens" - description: "This guide explains the various options of API authentication for uploading videos." +meta: + description: This page explains the various options of authentication using access tokens, refresh tokens, delegated upload tokens, private tokens, and session tokens. --- -# Upload & API Access Tokens +api.video provides you with various options of authentication that enable you to leverage the API on different levels of your application, whether it's on the frontend or the backend. Moreover, you can provide better security for your backend and videos using delegated upload tokens. -api.video provides you with various options of authentication which allows you to leverage the API on a different level of your application, whether it's on the front end or backend. Moreover, you can provide better security for your backend and videos. +# API access & upload tokens -## Access Token +## Access tokens -This token is created to enhance the backend security and create a short-lived bearer token that will replace your API key for any API request. The Access Token is a disposable bearer token that is being generated from the [/auth/api-key](https://docs.api.video/reference/post_auth-api-key) endpoint, by passing the workspace API key. The endpoint will respond with a short-lived bearer token (3600 seconds) that can be refreshed by making a request to the [/auth/refresh](https://docs.api.video/reference/post_auth-refresh) endpoint. +This token is created to enhance the backend security and create a short-lived bearer token that will replace your API key for any API request. The Access Token is a disposable bearer token that is being generated from the [/auth/api-key](/reference/api/Advanced-authentication#get-bearer-token) endpoint, by passing the workspace API key. The endpoint will respond with a short-lived bearer token (3600 seconds) that can be refreshed by making a request to the [/auth/refresh](/reference/api/Advanced-authentication#refresh-bearer-token) endpoint. -For more detailed information, head over to [the article about the Access Token](https://docs.api.video/reference/disposable-bearer-token-authentication) +For more detailed information, head over to [the article about the Access Token](/reference/disposable-bearer-token-authentication.md) -## Delegated Upload Token +## Delegated upload tokens The delegated upload token is created in order to assist you in building features in the front end. The delegated upload token is a one-time token that is valid only with the [/upload](https://docs.api.video/reference/post_upload) endpoint. The idea behind it is that you can serve a one-time token to the front end from the back end that will be used by the front-end to upload a video. For more details please visit the [Delegated upload tokens page](https://docs.api.video/reference/upload-tokens). -# Video Access Management Tokens +# Video access management tokens -## Private Token +## Private tokens In order for your user to consume private videos, api.video will generate a one-time private token for the assets to be passed as a query parameter. You can learn more about private videos and private tokens [here](https://docs.api.video/docs/private-videos). -## Session Token +## Session tokens This token's purpose is to retain a private session for private videos. When you serve private videos to your user, you will have to leverage session tokens to retrain the session and continue consuming other assets that are related to the video. Learn more about session tokens [here](https://docs.api.video/docs/private-video-session-tokens). \ No newline at end of file