RFC 8959

The "secret-token" URI Scheme

📅 published January 2021, from ietf

Internet Engineering Task Force (IETF) 💖

Okay bestie, let's get into it! This is RFC 8959, titled "The "secret-token" URI Scheme" 🎀

Here's the title block tea ☕:

Author: M. Nottingham (Mark Nottingham) ✨
Date: January 2021 🌸
Category: Informational 🦋 (so it's not a Standards Track thing, it's published just for info 💅)
ISSN: 2070-1721
Obsoletes / Updates: the title block doesn't list anything here, so no obsoleting or updating drama 🙈

Abstract ✨

okay so this doc registers the "secret-token" URI scheme 🔐 and the whole point is to help identify authentication tokens so they're easier to spot when they leak 💀

Status of This Memo 🌈

This one is not an Internet Standards Track spec, it's published for informational purposes 📖

It's a product of the IETF 🫶 and it has consensus from the IETF community, got public review, and was approved by the IESG. Not every IESG-approved doc is a candidate for any level of Internet Standard though, so see Section 2 of RFC 7841 for the deets 💅

Info on its current status, errata, and feedback can be found at https://www.rfc-editor.org/info/rfc8959 🔗

Copyright Notice 🎀

This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as of the publication date. Please actually read those, bestie, because they spell out your rights and restrictions 📜 Code Components pulled from this doc must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come without warranty as described in that license 🫶

Table of Contents 🧚

1. Introduction
- 1.1. Notational Conventions
2. The "secret-token" URI Scheme
3. IANA Considerations
4. Security Considerations
5. References
- 5.1. Normative References
- 5.2. Informative References
Acknowledgements
Author's Address

1. Introduction 🌸

It's giving everyone is using bearer tokens for auth now 🔑 Like, it's everywhere across different protocols.

A bearer token is a security token where anyone holding it (a "bearer") can use it in the same ways as any other holder 🦋 They don't have to prove they hold any cryptographic key material (that's the proof-of-possession thing) 🙈

The sad part? Accidental token leaks have been going up too 😭 We literally keep hearing about a dev committing an access token to a public source code repo, either because they didn't notice it was in the code or because they didn't get how bad it is to expose it 💀

So this spec registers the "secret-token" URI scheme to help stop those accidents ✨ When tokens are easier to identify, CI systems can throw warnings or repos can block them outright 🛡️ They can also be scanned for separately 🔍

For example, say cloud.example.net hands out access tokens to clients and formats them as "secret-token" URIs 🌈 If one of those tokens shows up somewhere it doesn't belong, it's way easier to spot. This could work through lots of different mechanisms. Like, if repo.example.com is set up to refuse commits containing "secret-token" URIs, its customers avoid accidental disclosures 💅

"secret-token" URIs are meant to help identify generated secrets, like API keys and similar tokens 🔐 They are not meant for situations where ephemeral tokens are used, like CSRF tokens 🙅‍♀️

1.1. Notational Conventions 📐

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here 💖

This doc uses ABNF [RFC5234]. It also uses the pchar rule from [RFC3986] 🧩

2. The "secret-token" URI Scheme 🎀

The "secret-token" URI scheme identifies a token that's meant to be a secret 🤫

secret-token-URI    = secret-token-scheme ":" token
secret-token-scheme = "secret-token"
token               = 1*pchar

See [RFC3986], Section 3.3 for the definition of pchar 🦋 Disallowed characters, including non-ASCII ones, MUST be encoded into UTF-8 [RFC3629] and then percent-encoded ([RFC3986], Section 2.1) 🫶

When a token is both generated and presented for authentication, the entire URI MUST be used, without changes ✨

For example, given the URI:

secret-token:E92FB7EB-D882-47A4-A265-A0B6135DC842%20foo

This string (character-for-character, case-sensitive) will both be issued by the token authority and required for later access 🔑 So if the example above were used as a bearer token in [RFC6750], a client might send:

GET /authenticated/stuff HTTP/1.1
Host: www.example.com
Authorization: Bearer
  secret-token:E92FB7EB-D882-47A4-A265-A0B6135DC842%20foo

3. IANA Considerations 🌷

This doc registers the following value in the "Uniform Resource Identifier (URI) Schemes" registry 📋

Scheme name:  secret-token
Status:  provisional
Applications/protocols that use this scheme:  none yet
Contact:  iesg@iesg.org
Change Controller:  IESG
References:  RFC 8959

4. Security Considerations 🚨

Okay, this part is serious bestie 😤 The token ABNF rule allows tokens as small as one character. This is not recommended practice, so applications should evaluate their entropy requirements and issue tokens to match 🔐 See [RFC4086] for more info 📖

This URI scheme is meant to reduce accidental disclosure. It cannot prevent intentional disclosure 💀

If it's difficult to handle secret material correctly, or it's unclear what the right handling is, users might obfuscate their secret tokens to dodge detection (like removing the URI scheme before storing them). Mitigating this risk is often beyond the reach of the system using the "secret-token" URI, so users can be warned against these habits and given tools to help 🫶

5. References 📚

5.1. Normative References 💜

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119,
           DOI 10.17487/RFC2119, March 1997,
           <https://www.rfc-editor.org/info/rfc2119>.

[RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO
           10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
           2003, <https://www.rfc-editor.org/info/rfc3629>.

[RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
           Resource Identifier (URI): Generic Syntax", STD 66,
           RFC 3986, DOI 10.17487/RFC3986, January 2005,
           <https://www.rfc-editor.org/info/rfc3986>.

[RFC5234]  Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
           Specifications: ABNF", STD 68, RFC 5234,
           DOI 10.17487/RFC5234, January 2008,
           <https://www.rfc-editor.org/info/rfc5234>.

[RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
           2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
           May 2017, <https://www.rfc-editor.org/info/rfc8174>.

5.2. Informative References 🦋

[RFC4086]  Eastlake 3rd, D., Schiller, J., and S. Crocker,
           "Randomness Requirements for Security", BCP 106, RFC 4086,
           DOI 10.17487/RFC4086, June 2005,
           <https://www.rfc-editor.org/info/rfc4086>.

[RFC6750]  Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
           Framework: Bearer Token Usage", RFC 6750,
           DOI 10.17487/RFC6750, October 2012,
           <https://www.rfc-editor.org/info/rfc6750>.

Acknowledgements 🧚

The definition of bearer tokens comes from [RFC6750] ✨

Author's Address 💌

Mark Nottingham Prahran VIC Australia

Email: mnot@mnot.net URI: https://www.mnot.net/

That's the whole RFC, bestie! 🌈💅✨

📦 where this page comes from

ietf: rfc8959 2021-01
💖 girlified by claude-haiku-5-5 on 2026-10-18: a language model's rewrite of the original, under its terms