Our New API uses the OAuth 2.1 framework, offering enhanced security, standardized authorization, and greater scalability compared to traditional single API key authentication. It implements the Client Credentials Grant flow, enabling backend services to securely obtain access tokens and interact with protected resources using their own credentials.
- Two-Factor Authentication: Combines client_id (app_key) and client_secret(app_secret) for dual verification.
- Short-Lived Access Tokens: Access tokens are valid for 30 minutes by default, reducing risk from compromised tokens.
- Scope-Based Access Control: API access is restricted according to the scope parameter.
- Token Revocation Mechanism: Token revocation endpoints are provided to mitigate potential exposure.
| Type | When to use | Considerations |
|---|---|---|
| Test mode | As you test and build your ShipSaving integration, use test mode with your test keys. In test mode, you can use all ShipSaving services such as retrieving shipping rates and creating sample labels without being charged. | Labels purchased in test mode are samples and cannot be used for actual shipping. Rates requested in test mode may differ from actual rates in live mode. Data is fully isolated from your live account. |
| Live mode | When your integration is ready for production, use live mode with your live tokens. In live mode, you can generate shipping rates and purchase real shipping labels. | Labels purchased in live mode are valid for actual shipping and will create real transaction records. Your account will be charged for purchasing labels. |
Signup for a ShipSaving API Portal account.
- Complete the registration form and verify your email.
- You can log in before verification, but API key creation is disabled until your email is verified.
- Once verified, you can manage keys and generate test or live API keys.
Log in to the ShipSaving API Portal and follow the on-screen steps (see GIF below) to create your API keys.
Once generated, your API key must be stored securely - it grants full access to your account. It is shown only once at creation; if the window closes, it cannot be retrieved.
Use your APP Key and APP Secret to obtain an access_token via the Client Credentials flow. Refer to the /oauth2/token API spec for full parameter and response details.
curl --location 'https://x-api.shipsaving.com/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic U1NfTElWRV9kWG8zT3k5V0VxS1k0ZnB1Q09Nd0N6Q19QanBJRHd1SnNXQ2Y6R1hBeFFkUUZHSWR5TElFVnhPTVY1amc1TjRma19YX3R0Nzc3' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=API'When calling other ShipSaving API endpoints, set Auth Type to Bearer Token and provide your access_token in the Token field. This grants access to the requested resources as long as the token remains valid.
- Token lifetime: Access tokens are valid for 30 minutes. Using an expired token will return 401 Unauthorized.
- One active token per appKey: At any time, only the most recently issued token for an appKey is valid. If you request two tokens in quick succession, the first token is revoked and only the second remains usable.
- Secret handling: Do not hard-code appSecret in client-side code. Store it securely (e.g., server-side secrets manager) to avoid leakage.