{"templateId":"markdown","versions":[{"version":"v5","label":"v5 (current)","link":"/authentication-scopes","default":true,"active":true,"folderId":"8a5edab2"},{"version":"v4","label":"v4","link":"/v4/authentication-scopes","default":false,"active":false,"folderId":"8a5edab2"},{"version":"v3","label":"v3 (legacy)","link":"/v3/authentication-scopes","default":false,"active":false,"folderId":"8a5edab2"}],"sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Authentication & Scopes","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"authentication--scopes","__idx":0},"children":["Authentication & Scopes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every v5 request uses a bearer token:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"Authorization: Bearer <token>\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Tokens are scoped and can optionally expire. Create the first token in the"," ","dashboard under ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Settings -> Integrations -> API"]},". A token with"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tokens:manage"]}," can create and revoke additional v5 tokens through the API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response-envelope","__idx":1},"children":["Response envelope"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Successful responses are wrapped in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"data\": {\n    \"id\": 12345,\n    \"status\": \"incomplete\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List endpoints also include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meta"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["links"]}," for pagination."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Errors are wrapped in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}," and include a stable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"error\": {\n    \"code\": \"validation_failed\",\n    \"message\": \"The given data was invalid.\",\n    \"details\": {\n      \"packages.0.weight\": [\"The packages.0.weight field is required.\"]\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Branch on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.code"]},", not the message text."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"pagination","__idx":2},"children":["Pagination"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List endpoints use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["per_page"]},". The default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["per_page"]}," is 25 and the"," ","maximum is 100."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET /shipments?page=2&per_page=50\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"scope-vocabulary","__idx":3},"children":["Scope vocabulary"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Scope"},"children":["Scope"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tokens:manage"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Manage API tokens."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addresses:validate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Validate addresses before creating shipments."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rates:read"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Quote shipping rates."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipments:read"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipments:write"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipments:void"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Shipment lifecycle."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["labels:create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Purchase and combine labels."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pickups:write"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Schedule and cancel carrier pickups."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tracking:read"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tracking:subscribe"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tracking lookups and notifications."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["batches:read"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["batches:write"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["batches:process"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bulk batch flow."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ltl:read"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ltl:write"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["LTL freight quotes and bookings."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["products:read"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["products:write"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Product catalog updates."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["products:classify"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["products:approve"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["DDP classification and approval."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["orders:read"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["orders:write"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Order CRUD."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["boxes:read"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["boxes:write"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Box preset CRUD."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["automation:read"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["automation:write"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rules, filters, lists, tags, and scheduled automations."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["billing:read"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Statements and transactions."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["credits:read"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["credits:write"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Credit balance and top-ups."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each operation in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi"},"children":["API Reference"]}," lists its required"," ","scope."]}]},"headings":[{"value":"Authentication & Scopes","id":"authentication--scopes","depth":1},{"value":"Response envelope","id":"response-envelope","depth":2},{"value":"Pagination","id":"pagination","depth":2},{"value":"Scope vocabulary","id":"scope-vocabulary","depth":2}],"frontmatter":{"seo":{"title":"Authentication & Scopes"}},"lastModified":"2026-06-11T19:50:44.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/authentication-scopes","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}