> For the complete documentation index, see [llms.txt](https://docs.tumbler.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tumbler.app/getting-started/url-protection-and-crypt3.md).

# When the URL must stay hidden: crypt3

## Who this is for

Security and DevOps teams that must not expose the raw subscription URL to the user or store it on the device.

## What you can do

* Decide when a raw HTTPS URL is enough and when `crypt3` is required.
* Hide the original subscription URL behind an encrypted source link.
* Configure signatures, TTL, and token rotation without breaking import.

## Examples

* Raw add link: `tumbler://add?link=https%3A%2F%2Fprovider.example.com%2Fsub%2Fu_123`.
* crypt3 source: `schema://crypt3/<token>`.
* crypt3 add link: `tumbler://add?link=schema%3A%2F%2Fcrypt3%2F...`.

## See also

* [getting-started/add-link.md](/getting-started/add-link.md)
* [security/fetcher-restrictions.md](/after-first-launch/fetcher-restrictions.md)
* [subscription/fetch-url.md](/getting-started/fetch-url.md)
* [operations/mirrors-and-migration.md](/after-first-launch/mirrors-and-migration.md)

## Two modes

### Raw HTTPS URL

Use this when the provider subscription URL may be shown to the user:

```
tumbler://add?link=https%3A%2F%2Fprovider.example.com%2Fsub%2Fu_123
```

Pros:

* easiest to implement;
* works with existing subscription endpoints;
* convenient for public or user-specific links with regular authorization.

Cons:

* the user and QR code can see the original URL;
* the link can be forwarded;
* the URL may remain in external system logs if you publish it as a normal link.

### crypt3

Use this when the raw URL is sensitive:

```
schema://crypt3/<token>
```

The `crypt3` token contains the encrypted subscription URL. The user receives only the wrapper:

```
tumbler://add?link=<url-encoded schema://crypt3/<token>>
```

When the user opens the link:

1. Tumbler sends `schema://crypt3/<token>` to the backend.
2. The backend recognizes the `://crypt3/` marker.
3. The backend decrypts the token with its private key.
4. The backend fetcher downloads the real subscription URL.
5. The client receives only the encrypted runtime payload, not the original URL.

## crypt3 source requirements

* The source link must contain `://crypt3/`, for example `schema://crypt3/<token>`.
* The public mechanism name is `crypt3`. Do not use `cryp3` in documentation or integrations.
* The token is encoded as URL-safe base64 without padding.
* The token must be created for the active public key from `/.well-known/crypt3`.
* During key rotation, keep a period where the old and new `kid` values are valid at the same time.

## Signatures and short raw URLs

`crypt3` hides the URL from the client, but it does not replace your server-side authorization. If the raw endpoint requires a signature:

* use HMAC/EdDSA or another deterministic signing algorithm;
* keep the TTL short enough for protection, but long enough for fetch and retry;
* do not use userinfo in URLs (`https://user:pass@example.com/sub`);
* return exact statuses `401`, `403`, `404`, `429`, not a generic `500`.

## Access errors

* 401 - signature or token is missing.
* 403 - signature is invalid or expired.
* 404 - URL is unavailable by policy; do not use 500 for authorization denials.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.tumbler.app/getting-started/url-protection-and-crypt3.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.