{"templateId":"markdown","versions":[{"version":"shipstation-v2","label":"ShipStation V2 API","link":"/apis/shipstation-v2/docs/partners/direct-login","default":true,"active":false,"folderId":"58c9a61d"},{"version":"shipengine","label":"ShipStation API (formerly ShipEngine)","link":"/apis/shipengine/docs/partners/direct-login","default":false,"active":true,"folderId":"58c9a61d"},{"version":"shipstation-v1","label":"ShipStation V1 API","link":"/apis/shipstation-v1/docs/partners/direct-login","default":false,"active":false,"folderId":"58c9a61d"}],"sharedDataIds":{"sidebar":"sidebar-apis/@shipengine/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Direct Login","keywords":"shipping, labels, shipstation, documentation, api","siteUrl":"https://docs.shipstation.com","lang":"en-US","llmstxt":{"hide":false,"title":"ShipStation API LLM Docs","description":"Find links and references to all markdown documentation for use with LLMs","excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"direct-login","__idx":0},"children":["Direct Login"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ShipStation API partners have the ability to create and manage ShipStation API accounts on behalf of their customers."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For your customers to access ShipStation API's discounted carrier rates, they must complete the ShipStation API ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/elements/onboarding/onboarding"},"children":["Onboarding Element"]}," or onboard within the ShipStation API Carrier Portal."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["During either process, your customer will need to accept carrier terms, enter billing information, and then fund a balance to pay for ShipStation Carrier labels."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"direct-login-to-the-carrier-portal","__idx":1},"children":["Direct Login to the Carrier Portal"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ShipStation API Carrier Portal is a special version of the ShipStation API Dashboard designed to let customers of partners complete a ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/partners/customize-theme"},"children":["branded onboarding wizard"]}," or manage carriers and billing information."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The direct login feature allows a partner to generate a URL to the ShipStation API Carrier Portal for a specific customer, without requiring them to enter their username or password."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide will go through how to generate a link to the ShipStation API Carrier Portal for your merchants."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"generate-a-token","__idx":2},"children":["Generate a Token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To access the ShipStation API Carrier Portal, you must generate an authorization token. This token has a 10 second lifespan so it should be generated just-in-time each time dashboard access is requested."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["On-Behalf-Of"]}," header should be set to the customer account ID for which you wish to generate an authorization token."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the “Configure a URL” section below for details on how to determine where the user is directed after successful authentication."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-request--response","__idx":3},"children":["Example Request & Response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /v1/tokens/ephemeral?redirect=shipengine-dashboard HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __PARTNER_API_KEY_HERE__\nOn-Behalf-Of: __ACCOUNT_ID_HERE__\nContent-Type: application/json\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"token\": \"eyJ..\",\n  \"redirect_url\": \"https://dashboard.shipengine.com/api/directlogin?token=eyJ..\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configure-a-url","__idx":4},"children":["Configure a URL"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The call to generate a token also generates a URL you can use to redirect your customer to the ShipStation API carrier portal."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirect_to"]}," parameter to determine which page your customer will land on by default. You can redirect to the Carriers, Billing, or Onboarding pages."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["theme_id"]}," parameter to this URL before redirecting your customer so they will be directed to a ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["branded"]}," experience."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Query parameters should be appended to the end of the URL string."]}]},{"$$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":"Query Parameter"},"children":["Query Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["theme_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The theme ID value, returned in the create theme response."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirect_to"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Available values are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carriers"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["billing"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onboarding"]},". ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," If onboarding is not complete, the customer will always be redirected to the Onboarding screen. Otherwise, if this parameter is not specified, the customer be redirected to the Carriers screen.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," If using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onboarding"]}," as the value but onboarding ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["is"]}," complete, the customer will be redirected to the Carriers page."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Review our ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/partners/customize-theme"},"children":["Customize the Onboarding Experience"]}," page for more details about creating a branded onboarding experience."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"url-max-length","__idx":5},"children":["URL Max Length"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["URLs are limited to 2000 characters in most browsers. The token and the root URL may take up to 700 characters, so your brand and return URL must total under 1300 characters."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"https://dashboard.shipengine.com/api/directlogin?token=eyJ..&theme_id=550e8400-e29b-41d4-a716-446655440000\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"default-experience","__idx":6},"children":["Default Experience"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Below you can find a series of screenshots for the onboarding default flow."]},{"$$mdtype":"Tag","name":"iframe","attributes":{"src":"https://docs.google.com/presentation/d/e/2PACX-1vTp5y7_lQ7gqVKABYMZsV7P3PQpc1Qb0EP6O14wz0v90n6ZUoPnTOhQKFEgOWqCjgJ-braaypVZil6M/embed?start=false&loop=true&delayms=3000","frameBorder":"0","width":"100%","height":"569","allowFullScreen":"true","mozallowfullscreen":"true","webkitallowfullscreen":"true"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"customizations","__idx":7},"children":["Customizations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following items can be customized in the onboarding experience for your customers using the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/partners/theme-reference"},"children":["Theme endpoint"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Custom logo image"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Custom start title and message"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Custom complete title and messge"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Carriers available for your customers to connect (by country)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We may offer partners additional customization of the ShipStation API Carrier Portal for an additional fee as part of their contractual agreement. Below are some of the bespoke options available:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Users subscribe to a ShipStation API billing plan"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Show additional discounted carriers"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["User can access label branding"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["User can access branded tracking page setup"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Whitelist/Blacklist Carriers"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Customer Chat Support"]}]}]},"headings":[{"value":"Direct Login","id":"direct-login","depth":1},{"value":"Direct Login to the Carrier Portal","id":"direct-login-to-the-carrier-portal","depth":2},{"value":"Generate a Token","id":"generate-a-token","depth":2},{"value":"Example Request & Response","id":"example-request--response","depth":3},{"value":"Configure a URL","id":"configure-a-url","depth":3},{"value":"URL Max Length","id":"url-max-length","depth":4},{"value":"Default Experience","id":"default-experience","depth":2},{"value":"Customizations","id":"customizations","depth":2}],"frontmatter":{"seo":{"title":"Direct Login"}},"lastModified":"2026-04-08T10:47:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/shipengine/docs/partners/direct-login","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}