# Signed Links

import Alert from "@/components/Alert.astro";

When you share links to the screenshots with your access key in public, there is a problem that everybody can take your API access key and reuse it to take screenshots on their own and exhaust your screenshot quota.

To prevent others from using your API key, you need to:
1. [Sign every request](https://screenshotone.com/docs/signed-requests/#signing-requests) you are going to share publicly.
2. [Require signing](https://screenshotone.com/docs/signed-requests/#require-signing) for every request.

Then even if the potential unscrupulous person sees or steals your access key, they can't reuse it until they also steal your secret key (signing key).

You generally don't need to sign requests if you will not share screenshot links publicly and will use screenshot API only on the server-side.

## Signing requests

<Alert>
Singed links do not work with HTTP "POST" requests. The feature is intended to be used for sharing links in public.
</Alert>

To sign the request, like `https://api.screenshotone.com/take?access_key=0Ij4LFMtFnGUrA&url=https://apple.com`, you need to follow the simple algorithm:

1. Use your secret to hash the query string `access_key=0Ij4LFMtFnGUrA&url=https://apple.com` with the HMAC SHA256 algorithm.
  
2. **Append** the signature parameter with the hash: `https://api.screenshotone.com/?access_key=0Ij4LFMtFnGUrA&url=https://apple.com&signature=70bea3e52efc43834129ecbea236f38bf9bb4a7cd7c2e1951017435defd4dbaf`.

**Do not sort the parameters. Or if you sort them, send them sorted, too.**
  
To hash the query string with your secret key and HMAC SHA256 algorithm in the CLI, you can run the following command:

```bash
$ echo -n "access_key=0Ij4LFMtFnGUrA&url=https://apple.com" | openssl sha256 -hmac "m9ajW9br9hTw2A"                     130 ↵

70bea3e52efc43834129ecbea236f38bf9bb4a7cd7c2e1951017435defd4dbaf
```

## Code examples

You can need to apply the same algorithm in the language of your choice.

### Python

For example, in Python:

```python
import urllib.parse
import hmac
import hashlib

def generate_signature(params: dict, secret_key: str) -> str:
    """
    Generate a signature for the given parameters using HMAC-SHA256.
    
    Args:
        params (dict): Dictionary of parameters to sign
        secret_key (str): Secret key used for signing
        
    Returns:
        str: The hexadecimal signature
    """        
    # convert parameters to URL-encoded query string
    query_string = urllib.parse.urlencode(params, doseq=True)

    signature = hmac.new(
        bytes(secret_key, "utf-8"),
        msg=bytes(query_string, "utf-8"),
        digestmod=hashlib.sha256,
    ).hexdigest()
    
    return signature