Authentication

The Login API provides JWT access tokens required for all protected endpoints.

Base Path: /api/v1

---

POST /api/v1/login

Standard login — returns access and refresh tokens.

Authentication: None (public endpoint)

Request:

{
  "username": "john.doe",
  "password": "SecureP@ssw0rd"
}

Field	Type	Required	Description
username	String	Mandatory	User login name
password	String	Mandatory	User password

Response 200 OK:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Status codes:

Code	Description
200 OK	Login successful
400 Bad Request	Validation error (missing fields)
401 Unauthorized	Invalid credentials

---

POST /api/v1/login-extended

Returns access token plus additional user info (depot code, expiry timestamp). Use this when your integration needs to know the depot code or exact token expiry.

Authentication: None (public endpoint)

Request: same as /login

Response 200 OK:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userName": "john.doe",
  "depotCode": "0699",
  "expireAt": "2025-10-30T18:30:00Z"
}

Field	Type	Description
token	String	JWT access token
refreshToken	String	JWT refresh token
userName	String	Authenticated username
depotCode	String	First non-empty depot code from user's pickup addresses
expireAt	ISO 8601	Token expiration timestamp

Status codes:

Code	Description
200 OK	Login successful
400 Bad Request	Validation error
401 Unauthorized	Invalid credentials
403 Forbidden	Auto-login context missing

---

Using tokens

Include the JWT in every subsequent request:

curl -X GET "https://label-print-shipments.dpd.ch/api/v1/tracking/05305000123456" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

const response = await fetch('https://label-print-shipments.dpd.ch/api/v1/shipments', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify(shipmentData)
});

Token expiry

• Default TTL is configured per environment (typically 24 hours)
• A 401 Unauthorized response means the token has expired
• Re-authenticate with /login to obtain a new token

Security checklist

• Always use HTTPS in production
• Store tokens in secure HTTP-only cookies or secure storage — never in localStorage
• Never expose tokens in URLs or log files
• Clear tokens on logout