Table of Contents

Authentication

POST /api/users/login

Overview

The Fredi API uses JWT (JSON Web Token)–based authentication to authorize API requests. All protected endpoints require a valid Bearer Access Token.

Authentication ensures:

  • Secure access to API resources
  • Identification of the authenticated user
  • Controlled access to shipment operations
  • Prevention of unauthorized access
Note

All API requests must be made over HTTPS in production environments!

How to Get API Credentials

To access the Fredi API, user authentication credentials must be provisioned.

Step 1️⃣ User Account Setup

Contact the Fredi support team to:

  • Create or activate your user account
  • Assign appropriate role(s)
  • Enable environment access (Test / Production)

You will receive:

  • Registered email
  • Initial password (or password setup link)
  • API Base URL

Step 2️⃣ Request an Access Token

Endpoint

POST /api/users/login
Base URL Content Type
https://staging.beo-fredi.de/api application/json

Request Body

Note

The schema tree below is automatically generated from the OpenAPI specification!

Loading schema…

Note

The example below is automatically generated from the OpenAPI specification!

Sample Request

{
  "email": "jon.snow@company.com",
  "password": "YourPassword",
  "rememberMe": "true",
  "otp": "string",
  "role": "string"
}

Responses

Status Code Description
200 Login successful
400 Bad Request
401 Invalid username or password
500 Internal Server Error

Response Format

200 Login Successful 
{
  "userId": 00000,
  "type": true,
  "firstName": "Jon",
  "lastName": "Snow",
  "email": "jon.snow@company.com",
  "beoClientId": 4,
  "uuid": "fbd4d17f-e0cb-4eb6-abd8-",
  "token": "eeyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "def50200a1b2c3...",
  "otp": false,
  "companyName": "Company Name"
}

Response Fields

Field Type Description
userId integer Unique identifier of the authenticated user
type boolean Indicates whether the requester is user or admin
firstName string User’s first name
lastName string User’s last name
email string Registered email address
beoClientId integer Associated BEO client identifier
uuid string (GUID) Unique system identifier for the user
token string JWT access token used for API authentication
refreshToken string Token used to obtain a new access token
otp boolean Indicates whether OTP verification is required
companyName string Name of the associated company

401 Unauthorized 
{
  "title": "Unauthorized",
  "status": 401,
  "traceId": "00-e348c454a38a7de1f5c506ca3fcfa30b-7dc9c267ea13612e-00"
}

Note
  • accessToken must be included in the Authorization header for subsequent API calls.
  • If otpRequired is true, an additional OTP verification step must be completed before full access is granted.
  • refreshToken should be stored securely and used only for token renewal.

How the API Authorization Works

  1. The client sends login credentials to /api/users/login.

  2. The API validates the credentials.

  3. If valid, the API returns:

    • accessToken
    • refreshToken

  4. The client securely stores the token.

  5. The client includes the accessToken in the Authorization header for all protected endpoints.

  6. The API validates the token before processing the request.

Using the Access Token

All protected endpoints (e.g., Create Shipment) require the token.

Authorization: Bearer <access_token>
Content-Type: application/json

Example Authentication Request

POST /api/v3/shipments
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Token Expiry & Refresh

  • Access tokens are valid for a limited duration (expiresIn)
  • Expired tokens return 401 Unauthorized
  • Use the refreshToken (if enabled) to obtain a new access token
  • If both tokens expire, the user must log in again

Security Best Practices

  • Never expose credentials in frontend code
  • Store tokens securely (HTTP-only cookies recommended)
  • Always use HTTPS in production
  • Do not log access tokens
  • Implement proper token expiration handling
Back to top ↑