Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / xet-protocol /main /en /auth.html

rtrm

about 2 months ago

download

raw

34.7 kB

	<meta charset="utf-8" /><meta name="hf:doc:metadata" content="{"title":"Authentication and Authorization","local":"authentication-and-authorization","sections":[{"title":"Token Request API Endpoints","local":"token-request-api-endpoints","sections":[{"title":"Response Format","local":"response-format","sections":[{"title":"Example Response Object","local":"example-response-object","sections":[],"depth":4}],"depth":3},{"title":"Error Handling","local":"error-handling","sections":[{"title":"HTTP Errors","local":"http-errors","sections":[],"depth":4}],"depth":3},{"title":"Implementation Example","local":"implementation-example","sections":[],"depth":3}],"depth":2},{"title":"Token Scope","local":"token-scope","sections":[],"depth":2},{"title":"Token Scope Relative to Hugging Face Hub Authentication Token","local":"token-scope-relative-to-hugging-face-hub-authentication-token","sections":[],"depth":2},{"title":"Security Considerations","local":"security-considerations","sections":[],"depth":2},{"title":"Diagram","local":"diagram","sections":[],"depth":2}],"depth":1}">
	<link href="/docs/xet-protocol/main/en/_app/immutable/assets/0.e3b0c442.css" rel="modulepreload">
	<link rel="modulepreload" href="/docs/xet-protocol/main/en/_app/immutable/entry/start.f721a4c7.js">
	<link rel="modulepreload" href="/docs/xet-protocol/main/en/_app/immutable/chunks/scheduler.b108d059.js">
	<link rel="modulepreload" href="/docs/xet-protocol/main/en/_app/immutable/chunks/singletons.47d4b706.js">
	<link rel="modulepreload" href="/docs/xet-protocol/main/en/_app/immutable/chunks/paths.5e4d7d49.js">
	<link rel="modulepreload" href="/docs/xet-protocol/main/en/_app/immutable/entry/app.b78ba70f.js">
	<link rel="modulepreload" href="/docs/xet-protocol/main/en/_app/immutable/chunks/index.008de539.js">
	<link rel="modulepreload" href="/docs/xet-protocol/main/en/_app/immutable/nodes/0.6d36c3e1.js">
	<link rel="modulepreload" href="/docs/xet-protocol/main/en/_app/immutable/nodes/3.ff1c08dd.js">
	<link rel="modulepreload" href="/docs/xet-protocol/main/en/_app/immutable/chunks/CodeBlock.7b00c886.js">
	<link rel="modulepreload" href="/docs/xet-protocol/main/en/_app/immutable/chunks/getInferenceSnippets.d2493432.js"><!-- HEAD_svelte-u9bgzb_START --><meta name="hf:doc:metadata" content="{"title":"Authentication and Authorization","local":"authentication-and-authorization","sections":[{"title":"Token Request API Endpoints","local":"token-request-api-endpoints","sections":[{"title":"Response Format","local":"response-format","sections":[{"title":"Example Response Object","local":"example-response-object","sections":[],"depth":4}],"depth":3},{"title":"Error Handling","local":"error-handling","sections":[{"title":"HTTP Errors","local":"http-errors","sections":[],"depth":4}],"depth":3},{"title":"Implementation Example","local":"implementation-example","sections":[],"depth":3}],"depth":2},{"title":"Token Scope","local":"token-scope","sections":[],"depth":2},{"title":"Token Scope Relative to Hugging Face Hub Authentication Token","local":"token-scope-relative-to-hugging-face-hub-authentication-token","sections":[],"depth":2},{"title":"Security Considerations","local":"security-considerations","sections":[],"depth":2},{"title":"Diagram","local":"diagram","sections":[],"depth":2}],"depth":1}"><!-- HEAD_svelte-u9bgzb_END --> <p></p> <h1 class="relative group"><a id="authentication-and-authorization" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#authentication-and-authorization"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Authentication and Authorization</span></h1> <p data-svelte-h="svelte-1myouam">To invoke any API’s mentioned in this specification a client MUST first acquire a token (and the URL) to authenticate against the server which serves these API’s.</p> <p data-svelte-h="svelte-18q4s5q">The Xet protocol server uses bearer authentication via a token generated by the Hugging Face Hub (<a href="https://huggingface.co" rel="nofollow">https://huggingface.co</a>).</p> <p data-svelte-h="svelte-ylhhzx">The following section explains how to acquire such a token.</p> <h2 class="relative group"><a id="token-request-api-endpoints" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#token-request-api-endpoints"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Token Request API Endpoints</span></h2> <p data-svelte-h="svelte-1tcp7mo"><strong>URL Pattern:</strong></p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class=""><!-- HTML_TAG_START -->https://huggingface.co/api/{repo_type}s/{repo_id}/xet-{token_type}-token/{revision}<!-- HTML_TAG_END --></pre></div> <p data-svelte-h="svelte-gyl88v"><strong>Parameters:</strong></p> <p data-svelte-h="svelte-m42jnh">All parameters are required to form the URL.</p> <ul data-svelte-h="svelte-13kv85b"><li><code>repo_type</code>: Type of repository - <code>model</code>, <code>dataset</code>, or <code>space</code></li> <li><code>repo_id</code>: Repository identifier in format <code>namespace/repo-name</code></li> <li><code>token_type</code>: Either <code>read</code> or <code>write</code>.</li> <li><code>revision</code>: Git revision (branch, tag, or commit hash; default to using <code>main</code> if no specific ref is required)</li></ul> <p data-svelte-h="svelte-d091v1">To understand the distinction for between <code>token_type</code> values read onwards in this document to <a href="./auth#token-scope">Token Scope</a>.</p> <p data-svelte-h="svelte-yzjc3b"><strong>Example URLs:</strong></p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class=""><!-- HTML_TAG_START -->https://huggingface.co/api/models/sentence-transformers/all-MiniLM-L6-v2/xet-read-token/main
	https://huggingface.co/api/datasets/HuggingFaceM4/the_cauldron/xet-write-token/v1.1
	https://huggingface.co/api/spaces/jsulz/ready-xet-go/xet-read-token/main<!-- HTML_TAG_END --></pre></div> <p data-svelte-h="svelte-eir0si"><strong>HTTP Method:</strong> GET</p> <p data-svelte-h="svelte-wzynsm"><strong>Required Headers:</strong></p> <ul data-svelte-h="svelte-1fql46b"><li><code>Authorization</code>: Bearer token for Hugging Face Hub authentication</li></ul> <h3 class="relative group"><a id="response-format" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#response-format"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Response Format</span></h3> <p data-svelte-h="svelte-1xmx4sp">A JSON encoded object with the following format:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class=""><!-- HTML_TAG_START -->{
	<span class="hljs-string">"accessToken"</span>: <span class="hljs-built_in">string</span>,
	<span class="hljs-string">"exp"</span>: <span class="hljs-built_in">number</span>,
	<span class="hljs-string">"casUrl"</span>: <span class="hljs-built_in">string</span>,
	}<!-- HTML_TAG_END --></pre></div> <ul data-svelte-h="svelte-n7ikyc"><li>accessToken is the token to be used when invoking API’s on the Xet CAS service (any Xet API denoted in this specification)</li> <li>exp is the unix timestamp of when this token expires</li> <li>casUrl is the API service endpoint URL</li></ul> <p data-svelte-h="svelte-sz174l">Users MAY assume the “accessToken” and “casUrl” fields lengths have an upper limit of 64000 characters.</p> <h4 class="relative group"><a id="example-response-object" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#example-response-object"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Example Response Object</span></h4> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class=""><!-- HTML_TAG_START --><span class="hljs-punctuation">{</span>
	<span class="hljs-attr">"accessToken"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"xet_xxxxxxxxxxx"</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"exp"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1848535668</span><span class="hljs-punctuation">,</span>
	<span class="hljs-attr">"casUrl"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"https://cas-server.xethub.hf.co"</span>
	<span class="hljs-punctuation">}</span><!-- HTML_TAG_END --></pre></div> <h3 class="relative group"><a id="error-handling" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#error-handling"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Error Handling</span></h3> <h4 class="relative group"><a id="http-errors" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#http-errors"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>HTTP Errors</span></h4> <ul data-svelte-h="svelte-y0j74v"><li><strong>401 Unauthorized</strong>: Invalid or missing Hub authentication token</li> <li><strong>403 Forbidden</strong>: Insufficient permissions for the requested token type</li> <li><strong>404 Not Found</strong>: Repository or revision does not exist</li></ul> <h3 class="relative group"><a id="implementation-example" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#implementation-example"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Implementation Example</span></h3> <p data-svelte-h="svelte-10cm6pp">Here’s a basic implementation flow:</p> <ol><li><p data-svelte-h="svelte-4yemcr"><strong>Make the request:</strong></p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class=""><!-- HTML_TAG_START -->GET /api/models/black-forest-labs/FLUX.1-dev/xet-read-token/main
	<span class="hljs-attribute">Host</span><span class="hljs-punctuation">: </span>huggingface.co
	<span class="hljs-attribute">Authorization</span><span class="hljs-punctuation">: </span>Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx<!-- HTML_TAG_END --></pre></div></li> <li><p data-svelte-h="svelte-1b5v3no"><strong>Parse the response</strong></p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class=""><!-- HTML_TAG_START -->endpoint = response_json[<span class="hljs-string">"casUrl"</span>]
	access_token = response_json[<span class="hljs-string">"accessToken"</span>]
	expiration = response_json[<span class="hljs-string">"exp"</span>]<!-- HTML_TAG_END --></pre></div></li> <li data-svelte-h="svelte-70qh2n"><p><strong>Use the token with Xet service:</strong>
	Use Bearer authentication with the value for the <code>accessToken</code> key to authenticate with the Xet service at <code>endpoint</code> until <code>expiration</code> time.</p></li> <li data-svelte-h="svelte-gvnawy"><p><strong>Token refresh (when needed):</strong>
	Use the same API to generate a new token.</p> <blockquote class="note"><p>In <code>xet-core</code> we SHOULD add 30 seconds of buffer time before the provided <code>expiration</code> time to refresh the token.</p></blockquote></li></ol> <h2 class="relative group"><a id="token-scope" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#token-scope"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Token Scope</span></h2> <p data-svelte-h="svelte-882wgm">Xet tokens can have either a <code>read</code> or a <code>write</code> scope.
	<code>write</code> scope supersedes <code>read</code> scope and all <code>read</code> scope API’s can be invoked when using a <code>write</code> scope token.
	The type of token issued is determined on the <code>token_type</code> URI path component when requesting the token from the Hugging Face Hub (see above).</p> <p data-svelte-h="svelte-13jj1ub">Check API specification for what scope level is necessary to invoke each API (briefly, only <code>POST /shard</code> and <code>POST /xorb/*</code> API’s require <code>write</code> scope).</p> <p data-svelte-h="svelte-wh27bp">The scope of the Xet tokens is limited to the repository and ref for which they were issued. To upload or download from different repositories or refs (different branches) clients MUST be issued different tokens.</p> <h2 class="relative group"><a id="token-scope-relative-to-hugging-face-hub-authentication-token" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#token-scope-relative-to-hugging-face-hub-authentication-token"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Token Scope Relative to Hugging Face Hub Authentication Token</span></h2> <p data-svelte-h="svelte-wrcyfr">When requesting a Xet token from the Hugging Face Hub, you will only receive a Xet token matching the requested parameters if you actually have access to them, based on the access afforded to your Hub authentication token.</p> <p data-svelte-h="svelte-1m39mey">If you require a <code>write</code> scope Xet token, then you MUST request it using a Hugging Face Hub token that has write access to the particular repository and ref that you want to access.</p> <p data-svelte-h="svelte-1y8jpil">If you request a <code>read</code> scope Xet token, then you MUST request it using a Hugging Face Hub token that has at least read access to the particular repository and ref you want to access.</p> <p data-svelte-h="svelte-nofkvt">If you are using Fine-grained Hugging Face Hub Access Tokens, your tokens MUST have read or write access to the contents of repositories to be issues read or write Xet tokens respectively.</p> <h2 class="relative group"><a id="security-considerations" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#security-considerations"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Security Considerations</span></h2> <ul data-svelte-h="svelte-1sl7wzk"><li>Xet tokens are time-limited and SHOULD be refreshed/swapped before expiration</li> <li>Store tokens securely and SHOULD NOT log them (both Hub authentication tokens and Xet tokens)</li> <li>SHOULD use read tokens when possible; only request write tokens when necessary</li></ul> <h2 class="relative group"><a id="diagram" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#diagram"><span><svg class="" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg></span></a> <span>Diagram</span></h2> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg class="" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg> <div class="absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0"><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent; "></div> Copied</div></button></div> <pre class=""><!-- HTML_TAG_START -->sequenceDiagram
	autonumber
	actor C <span class="hljs-keyword">as</span> Client
	participant H <span class="hljs-keyword">as</span> Hugging Face <span class="hljs-title function_ invoke__">Hub</span> (https:<span class="hljs-comment">//huggingface.co)</span>
	participant CAS <span class="hljs-keyword">as</span> CAS API

	<span class="hljs-keyword">loop</span> Repeat after token expiration
	C<span class="hljs-punctuation">-></span>>H: https:<span class="hljs-comment">//huggingface.co/api/{repo_type}s/{repo_id}/xet-{token_type}-token/{revision}</span>
	H<span class="hljs-punctuation">-></span>>C: { casUrl, accessToken, exp }

	<span class="hljs-keyword">loop</span> Client invoking CAS API<span class="hljs-symbol">'s</span>
	C<span class="hljs-punctuation">-></span>>CAS: CAS API<span class="hljs-symbol">'s</span> using accessToken and casUrl<br/>(Reconstruction, Xorb & Shard upload, Global Dedupe)
	CAS<span class="hljs-punctuation">-></span>>C: API Responses, returns code <span class="hljs-number">401</span> Unauthorized <span class="hljs-keyword">if</span> token expired
	end
	end<!-- HTML_TAG_END --></pre></div> <a class="!text-gray-400 !no-underline text-sm flex items-center not-prose mt-4" href="https://github.com/huggingface/xet-core/blob/main/docs/source/auth.md" target="_blank"><span data-svelte-h="svelte-1kd6by1"><</span> <span data-svelte-h="svelte-x0xyl0">></span> <span data-svelte-h="svelte-1dajgef"><span class="underline ml-1.5">Update</span> on GitHub</span></a> <p></p>

	<script>
	{
	__sveltekit_1w0vdne = {
	assets: "/docs/xet-protocol/main/en",
	base: "/docs/xet-protocol/main/en",
	env: {}
	};

	const element = document.currentScript.parentElement;

	const data = [null,null];

	Promise.all([
	import("/docs/xet-protocol/main/en/_app/immutable/entry/start.f721a4c7.js"),
	import("/docs/xet-protocol/main/en/_app/immutable/entry/app.b78ba70f.js")
	]).then(([kit, app]) => {
	kit.start(app, element, {
	node_ids: [0, 3],
	data,
	form: null,
	error: null
	});
	});
	}
	</script>

Xet Storage Details

Size:: 34.7 kB
Xet hash:: 0dc9d453d1fdb5ac9b34e0b795941993c1fea92a83eee418d90fe6e6c6c6acf2

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.