​

Authentication

ParcelShield APIs use Bearer token authentication. To authenticate your requests, you’ll need to:

1. Obtain an access token
2. Include the token in your API requests

​

Getting an Access Token

To get an access token, send a POST request to the token endpoint with your client credentials:

curl --request POST \
  --url https://auth.parcelshield.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "YOUR_API_IDENTIFIER",
    "grant_type": "client_credentials"
}'

The response will include your access token:

{
  "access_token": "eyJz93a...k4laUWw",
  "token_type": "Bearer",
  "expires_in": 86400
}

​

Using the Access Token

Once you have an access token, include it in the Authorization header of your API requests:

curl --request GET \
  --url https://api.parcelshield.com/v1/your-endpoint \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

​

Token Lifecycle

• Access tokens are valid for 24 hours (86400 seconds)
• You should request a new token when the current one expires
• Store tokens securely and never expose them in client-side code
• Implement token refresh logic in your application to maintain continuous access

​

Best Practices

​

Rate Limits

​

Error Responses

If authentication fails, you’ll receive one of these common error responses:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

{
  "error": "access_denied",
  "error_description": "Unauthorized"
}

Common HTTP status codes:

• 401 - Invalid or expired token
• 403 - Valid token but insufficient permissions
• 429 - Rate limit exceeded