Implementing Liminal’s Limited-Use API Key 

Making the /sign call 

To get started you need to have a Liminal API Key. The sandbox does not support single and limited-use API keys. For instructions on creating an account or getting an API Key, visit Getting Started with the API Hub. 

Arguments 

Argument	Description	Required/Optional
Carrier	The numeric carrier listed on the /tracking page, or the 4-letter SCAC referenced by the carrier in /account/api-keys	Required
Methods	One or more comma-separated methods (status,date,lading,proof,rating), defaults to status	Optional
Count	Integer, number of returns allowed	Optional
Duration	Length of key validity in seconds, up to 2562000 (30 days), defaults to 300 (5 minutes)	Optional
pro		One of pro, bol, or tracking
bol		One of pro, bol, or tracking
tracking		One of pro, bol, or tracking

The Liminal Network Limited-Use API provides single or multi-use links with limited lifetimes, which can be used for embedding API responses or image resources in your web page, providing links in emails to send to customers or clients, or anywhere you can think of where you would like to include your data, but necessarily need to keep your API key secure (no one wants their API keys leaked). 

When making the /sign call for later /status, /date, /lading, or /proof calls, you are limited to a single PRO, BOL, or Tracking number at any time, which must be included as part of the /sign call. The inclusion of additional PRO, BOL, or Tracking numbers later will be ignored. The exception is the use of the /rating method, which does not require the use of any PRO, BOL, or Tracking number to operate, allowing for those arguments to be omitted when signing for /rating only. 

Limited-use API Keys are constructed with an optional count=number argument, with count being 1…100, defaulting to 1. You will also want to pay attention to the duration=seconds argument, with duration being 1…2592000, which is up to 30 days, defaulting to 300 (5 minutes). 

For some examples, if you would like to get a link that can be used to fetch proof-of-delivery images via an email link for 14 days, then you would call the below function like: 

embed_key = limited_use_key(carrier, “proof”, 100, 1209600, pro=...) 

Or if you want to embed the image on your web page where you wouldn’t need that many fetches or such a high duration, and the following call is likely to work well: 

embed_key = limited_use_key(carrier, “proof”, 3, pro=...) 

Each limited-use API key can be used at most once every 10 seconds. 

def limited_use_key( 
    carrier: Union[str, int], 
    methods: Union[list, tuple, set, str] = "status", 
    count: int = 1, 
    duration: int = 300, 
    pro: str = None, 
    bol: str = None, 
    tracking: str = None, 
) -> Union[str, dict]: 
    # provide one of pro=, bol=, or tracking= 
    if not isinstance(methods, str): 
        methods = ",".join(methods) 
    methods = methods.replace("&", "") 
    base = url.format( 
        scac=carrier, 
        method="sign", 
        pro=pro, 
        api_key=settings.LIMINAL_NETWORK_API_KEY, 
    ) + ( 
        f"&methods={methods}&count={count}&duration={duration}" 
    ) 
    
if not pro: 
        # one of the other two should be valid 
        rep = ("bol=" + bol) if bol else ("tracking=" + tracking) 
        base = base.replace("pro=", rep, 1) 

ret = json.loads(urllib.request.urlopen(base).read().decode()) 
if "auth" in ret: 
    return ret["auth"] 
 
   # there was an error 
    return ret 

Error Messages 

Frequent error messages include: 
  {"errors": ["duration is out of range"]} 
  (use a shorter or longer duration; 1...2592000 are valid) 
  {"errors": ["count is out of range"]} 
  (use a smaller or larger count; 1...100 are valid) 
  {"errors": ["missing pro, bol, and tracking"]} 
  (include one of pro, bol, or tracking in your arguments) 

If you receive the error: 
  {"errors": ["only single-carrier calls can be signed at this time"]}

Then you need to include the SCAC or the numeric carrier identifier. Find the 4-letter SCAC or your unique numeric carrier key ids by visiting carrier keys or find the numeric carrier identifier by visiting the tracking page, then select your carrier, fill out the rest of the form, and hit submit. Below the Submit button you’ll see URL that was generated, like: 

https://api.liminalnetwork.com/111/status?pro=123&auth=YOUR_API_KEY

The numeric carrier ID is in bold.

Using the Limited-Use Key 

Using the Limited-Use Key is nearly the same as using a regular API Key; only instead of using your API Key, you use the limited-use key, pick your specified API call, and call with only the auth= argument: 

https://api.liminalnetwork.com/status?auth=LIMITED_USE_KEY
https://api.liminalnetwork.com/date?auth=LIMITED_USE_KEY
https://api.liminalnetwork.com/lading?auth=LIMITED_USE_KEY
https://api.liminalnetwork.com/proof?auth=LIMITED_USE_KEY

When you have signed the /rating method, you will need to include all normal standard arguments to /rating .