---
title: "Using URS Protected Links"
canonical: "https://docs.pbs.org/space/URS/3577377/Using+URS+Protected+Links"
format: markdown
---
> Macro (toc)

## What happens when you get a URS link?

First, it looks like:  http://urs.pbs.org/redirect/some-uid-here

An example:  [http://urs.pbs.org/redirect/nvk4k8jf9smtmy8snd9fnf9sjd0sdjs02n3](http://urs.api.pbs.org/redirect/nvk4k8jf9smtmy8snd9fnf9sjd0sdjs02n3)

The above URL redirects the client to original url and provides a 302 HTTP status code.  

> ℹ️ The above link is non-functioning and was created for the sole purpose of illustrating the concepts here.

## <span style="color: #000000">Using the URS protected link</span>

If you load this url in a browser or software, then URS will follow this decision flow:

| **If...** | **URS returns...** |
| --- | --- |
| The protected link does not match any known registered link | [HTTP 404] |
| Your IP is:<br>1. Detected to **not** be in a country that matches the allowed list or in a country that is on the restricted list
2. Detected to be coming from a VPN proxy, and you are attempting to access a show which restricts anonymous IPs. (Anonymous IP restriction applies only to a small number of specific shows, not all PBS content.) | [HTTP 403] |
| The current time is before the allowed time window | [HTTP 404] |
| The current time is after the allowed time window | [HTTP 410] |
| **All other times...** |  |
| (Unless alternate formats are requested - see below) | [HTTP 302] |

## <span style="color: #000000">Alternate Formats</span>

Sometimes, you don't want just the HTTP 302 redirect.  For example, this is not generally useful in a javascript AJAX call.  Thus, URS exposes some additional functionality

## JSON redirect

There are two ways to access a protected URL and receive a JSON response (not HTTP Redirect):

1. By providing format as a query parameter:  [http://urs.api.pbs.org/redirect/nvk4k8jf9smtmy8snd9fnf9sjd0sdjs02n3?format=json](http://urs.api.pbs.org/redirect/nvk4k8jf9smtmy8snd9fnf9sjd0sdjs02n3?format=json)
2. The second option is to provide "application/json" in Accept header.  [http://urs.api.pbs.org/redirect/nvk4k8jf9smtmy8snd9fnf9sjd0sdjs02n3](http://urs.api.pbs.org/redirect/nvk4k8jf9smtmy8snd9fnf9sjd0sdjs02n3)

In both cases the response will be one of the following (200 HTTP status code):

1. If the Redirect is expired, the following response is returned:
  If the Redirect doesn't exists or is not yet available the following code is returned:
  If the Redirect is blocked due to a geo-restriction or because the particular show does not allow anonymous IPs, the following code is returned:
2. If the Redirect is available:

## <span style="color: #000000">JSONP redirect</span>

There are two ways to access a protected URL and receive a JSONP response (not HTTP Redirect)

1. By providing format and callback as query parameters:  
[http://urs.pbs.org/redirect/nvk4k8jf9smtmy8snd9fnf9sjd0sdjs02n3?format=jsonp&callback=mycallback](http://urs.pbs.org/redirect/nvk4k8jf9smtmy8snd9fnf9sjd0sdjs02n3?format=jsonp&callback=mycallback)
2. The second option is to provide "application/javascript" in Accept header and callback method in "X-JSONP-Callback" custom header  
[http://urs.pbs.org/redirect/nvk4k8jf9smtmy8snd9fnf9sjd0sdjs02n3](http://urs.pbs.org/redirect/nvk4k8jf9smtmy8snd9fnf9sjd0sdjs02n3)

In both cases 400 HTTP status code is returned if the callback query param is missing or no value is specified. If everything is ok, 200 HTTP status code is returned with the following body:

1. If the Redirect is expired, will return the following response is returned:
  If the Redirect doesn't exists or is not yet available the following code is returned:
  If the Redirect is geoblocked, the following code is returned:
2. If the Redirect is available: