A Third-Party Developer user (or developer user) is a ShipHero user created for an external integration that connects to the ShipHero GraphQL Public API. When you create a developer user, ShipHero generates the API Access Token and Refresh Token the integration uses to connect. These tokens are sometimes called API keys or API credentials.
Before You Begin
- Unique email: The developer user needs an email address that no other ShipHero user has. The same email cannot be used for more than one user.
- Account: Create the developer user in the ShipHero account the integration needs to access. API tokens only work in the account where they were created.
Developer user or regular user? Use a developer user when a third-party integration or a custom-built app needs its own API tokens. To connect an AI assistant through the ShipHero MCP or the ShipHero Public API Skill, give a regular ShipHero user API access instead. See How to Give a ShipHero User API Access and Overview: ShipHero AI Toolkit.
Table of Contents
- How to Create a ShipHero Developer User and Get API Tokens
- ShipHero API Token Expiration and Account Rules
- ShipHero API Tokens for Regular Users: Permissions and MFA
- How to Revoke ShipHero Developer User Tokens
How to Create a ShipHero Developer User and Get API Tokens
Create a developer user from the Developer Users page. ShipHero shows the new developer user's API Access Token and Refresh Token as soon as the user is created.
- Go to the My Account > Developer Users page.
-
Select Add Third-Party Developer at the top of the Developer Users page.
- Enter the developer's First Name, Last Name, and Email, then select Add Developer.
- Copy the API Access Token and Refresh Token that appear, and send them to your developer.
The ShipHero API Access Token Is Only Shown Once
ShipHero displays the API Access Token only once, right after the developer user is created. Copy it before you leave the page. If you lose the Access Token, or it expires, use the Refresh Token to generate a new one.
To give a developer user access to Recurring Data Exports, select Enable Data Exports on the Developer Users page. See How to Give Users Access to Recurring Data Exports.
ShipHero API Token Expiration and Account Rules
ShipHero API Access Tokens expire after 28 days. Refresh Tokens stay active as long as the account is active and the token is used at least once every 90 days. These rules apply to every developer user:
- The Refresh Token remains active and does not change as long as the associated account is active and the developer user is not deactivated.
- The API Access Token expires after 28 days. Use the Refresh Token to generate a new Access Token. For the request format, see the ShipHero developer documentation.
- API tokens that go unused for 90 days are revoked. Review integrations that run only occasionally. When a revoked token stops an integration, create new tokens for it.
- API tokens are tied to the account where they were created and only work in that account.
- When an account is canceled, suspended, or inactive, its tokens do not work, even if generating a token appears successful.
- Create a separate developer user for each third-party integration to avoid account-related problems.
ShipHero API Tokens for Regular Users: Permissions and MFA
A regular ShipHero user with API access can use API tokens, and those tokens follow that user's permissions. Developer users have full permissions, so these rules do not limit them.
ShipHero API Token Permissions for Regular Users
When an integration performs an action its user is not permitted to perform in ShipHero, the call fails even when the token is still valid. The API response describes the permission the user needs. To fix a failing integration, grant the user the permissions it needs on the Users & Roles page, or create a dedicated user with the right permissions for that integration. See How to Create and Manage Roles and Permissions.
ShipHero API Tokens for Regular Users With MFA
A regular user with MFA turned on can get API tokens. When the user requests tokens, ShipHero asks for the MFA verification. The user completes it once, stores the tokens, and then uses the refresh token to get a new access token when the current one expires. Do not send a username and password each time your integration needs a token. For how MFA works for users, see How to Manage Multi-Factor Authentication (MFA) for Users.
ShipHero Username and Password Token Requests Are Being Retired
ShipHero plans to stop exchanging a username and password for access and refresh tokens. This does not invalidate tokens you already have. Renewing an access token with your refresh token is not changing, so keep using your refresh token. If your integration creates new tokens with a username and password, update that step to generate tokens in ShipHero instead. For the request format, see the ShipHero developer documentation.
How to Revoke ShipHero Developer User Tokens
To stop a developer user's tokens from working, select De-activate for the developer user on the Developer Users page. Deactivating a developer user stops both its API Access Token and its Refresh Token. You cannot reactivate a developer user, so create a new developer user to get new tokens. For the steps, see How to Revoke ShipHero API Access Tokens.