[{"data":1,"prerenderedAt":249},["ShallowReactive",2],{"changelog:off-route":3,"\u002Fauthentication":4,"docs-nav":211},null,{"id":5,"title":6,"body":7,"cards":3,"description":200,"extension":201,"group":202,"hero":3,"icon":203,"meta":204,"navTitle":3,"navigation":205,"order":93,"path":206,"seo":207,"sitemap":208,"stem":13,"__hash__":210},"docs\u002Fauthentication.md","Authentication",{"type":8,"value":9,"toc":193},"minimark",[10,14,18,23,47,50,54,62,97,100,111,115,118,143,150,163,167,173,176,180,186,189],[11,12,6],"h1",{"id":13},"authentication",[15,16,17],"p",{},"Every request needs a Personal Access Token, sent in a header. There is no OAuth\nflow, no client registration and no key to request from us — you create the token\nyourself and it works immediately.",[19,20,22],"h2",{"id":21},"creating-a-token","Creating a token",[24,25,26,30,38,41],"ol",{},[27,28,29],"li",{},"Sign in to Cargoplot and open your profile.",[27,31,32,33,37],{},"Go to ",[34,35,36],"strong",{},"Access tokens",".",[27,39,40],{},"Create one, and give it a name you will recognise in six months.",[27,42,43,46],{},[34,44,45],{},"Copy it now."," It is shown once. We store only a hash, so we cannot show it\nto you again or recover it if you lose it.",[15,48,49],{},"A token carries your own permissions. It can read exactly what you can read in\nthe app — no more — and if your access changes, the token's access changes with\nit.",[19,51,53],{"id":52},"using-it","Using it",[15,55,56,57,61],{},"Send it in the ",[58,59,60],"code",{},"X-Cargoplot-Key"," header:",[63,64,69],"pre",{"className":65,"code":66,"language":67,"meta":68,"style":68},"language-bash shiki shiki-themes github-dark github-dark","curl -H 'X-Cargoplot-Key: \u003CuserID>|\u003Cuuid>' \\\n  'https:\u002F\u002Fapi.cargoplot.com\u002Fv1\u002Fshipment'\n","bash","",[58,70,71,91],{"__ignoreMap":68},[72,73,76,80,84,88],"span",{"class":74,"line":75},"line",1,[72,77,79],{"class":78},"sFR8T","curl",[72,81,83],{"class":82},"s8ozJ"," -H",[72,85,87],{"class":86},"s4wv1"," 'X-Cargoplot-Key: \u003CuserID>|\u003Cuuid>'",[72,89,90],{"class":82}," \\\n",[72,92,94],{"class":74,"line":93},2,[72,95,96],{"class":86},"  'https:\u002F\u002Fapi.cargoplot.com\u002Fv1\u002Fshipment'\n",[15,98,99],{},"The token has two parts joined by a pipe: your numeric user ID, then a secret.\nSend the whole string exactly as it was given to you — both halves are part of\nthe credential.",[15,101,102,103,106,107,110],{},"Not a ",[58,104,105],{},"Bearer"," token: ",[58,108,109],{},"Authorization"," on this API is for the browser session the\napp itself uses, and sending your access token there will not authenticate you.",[19,112,114],{"id":113},"if-it-does-not-work","If it does not work",[15,116,117],{},"A missing, malformed or revoked token gives you:",[63,119,123],{"className":120,"code":121,"language":122,"meta":68,"style":68},"language-json shiki shiki-themes github-dark github-dark","{ \"message\": \"invalid API key\" }\n","json",[58,124,125],{"__ignoreMap":68},[72,126,127,131,134,137,140],{"class":74,"line":75},[72,128,130],{"class":129},"suv1-","{ ",[72,132,133],{"class":82},"\"message\"",[72,135,136],{"class":129},": ",[72,138,139],{"class":86},"\"invalid API key\"",[72,141,142],{"class":129}," }\n",[15,144,145,146,149],{},"with status ",[58,147,148],{},"401",". The message is deliberately the same for all three, so an\nattacker cannot use the response to learn whether a token exists.",[15,151,152,153,155,156,158,159,162],{},"If you get a ",[58,154,148],{}," you did not expect, check in this order: the header name is\nspelled exactly ",[58,157,60],{},"; the token includes the ",[58,160,161],{},"\u003CuserID>|"," prefix; the\ntoken has not been revoked in your profile.",[19,164,166],{"id":165},"revoking","Revoking",[15,168,169,170,172],{},"Delete a token from the same ",[34,171,36],{}," screen. It stops working\nimmediately — there is no grace period and nothing to wait for. Revoke rather\nthan rotate if a token may have leaked: a leaked token is usable by anyone until\nyou do.",[15,174,175],{},"Create a separate token per integration. One token per script means you can\nrevoke the one that leaked without taking down everything else you have built.",[19,177,179],{"id":178},"keeping-it-safe","Keeping it safe",[181,182,183],"warning",{},[15,184,185],{},"A Personal Access Token is a password that reads your company's shipping data.\nTreat it like one: keep it in a secret store or an environment variable, never in\na repository, a frontend bundle, a URL or a support ticket.",[15,187,188],{},"There is no browser-based \"try it out\" on this site, deliberately — we would\nrather not invite anyone to paste a live credential into a web page.",[190,191,192],"style",{},"html pre.shiki code .suv1-, html code.shiki .suv1-{--shiki-default:#E1E4E8;--shiki-dark:#E1E4E8}html pre.shiki code .s8ozJ, html code.shiki .s8ozJ{--shiki-default:#79B8FF;--shiki-dark:#79B8FF}html pre.shiki code .s4wv1, html code.shiki .s4wv1{--shiki-default:#9ECBFF;--shiki-dark:#9ECBFF}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sFR8T, html code.shiki .sFR8T{--shiki-default:#B392F0;--shiki-dark:#B392F0}",{"title":68,"searchDepth":93,"depth":93,"links":194},[195,196,197,198,199],{"id":21,"depth":93,"text":22},{"id":52,"depth":93,"text":53},{"id":113,"depth":93,"text":114},{"id":165,"depth":93,"text":166},{"id":178,"depth":93,"text":179},"Create a Personal Access Token and send it in the X-Cargoplot-Key header.","md","getting-started","mdi-key-variant",{},true,"\u002Fauthentication",{"title":6,"description":200},{"loc":206,"lastmod":209},"2026-08-20","BOUpZ-6B3l61J_exh59aLlwlsihaFwkgwMU3jU9kLho",[212,216,217,223,228,233,238,243],{"path":213,"title":214,"navTitle":214,"icon":215,"group":202,"order":75},"\u002F","Overview","mdi-book-open-page-variant-outline",{"path":206,"title":6,"navTitle":3,"icon":203,"group":202,"order":93},{"path":218,"title":219,"navTitle":3,"icon":220,"group":221,"order":222},"\u002Ftracking","Shipment tracking","mdi-map-marker-path","working",3,{"path":224,"title":225,"navTitle":3,"icon":226,"group":221,"order":227},"\u002Frate-limits","Rate limits","mdi-speedometer",4,{"path":229,"title":230,"navTitle":3,"icon":231,"group":221,"order":232},"\u002Fpagination","Pagination and filtering","mdi-filter-variant",5,{"path":234,"title":235,"navTitle":3,"icon":236,"group":221,"order":237},"\u002Ferrors","Errors","mdi-alert-outline",6,{"path":239,"title":240,"navTitle":3,"icon":241,"group":221,"order":242},"\u002Fglossary","Glossary","mdi-book-alphabet",7,{"path":244,"title":245,"navTitle":3,"icon":246,"group":247,"order":248},"\u002Fversioning","Versioning","mdi-tag-outline","current",8,1789636124841]