Authentication Guide

This guide explains how to authenticate with the entervo infinite API and access the API documentation.

Authentication Overview

The entervo infinite API uses OAuth 2.0 for authentication. To access the API, you need to:

1. Log in to the Program Manager with an existing user
2. Generate an access token using the Identity Access Management service
3. Include the token in your API requests

important

This chapter covers OAuth 2.0 Authentication, which is applied to all APIs except for online authorization with third-party mobility providers. That process is handled through S&B’s eConnect interface, using the AuthCode authorization type.

Accessing the Swagger Documentation

To access the Swagger documentation on the Pre-Production System of Scheidt & Bachmann Parking Solution GmbH for Customer & Contracts, you must first log in to the Program Manager with an existing user.

1. Use this URL to log in:
   https://pm.preprod.parking.scheidt-bachmann.net/pmui/YOURPROJECT
2. After logging in, you can access the Swagger documentation at:
   https://pm.preprod.parking.scheidt-bachmann.net/customers-contracts/swagger-ui/index.html

YOURPROJECT

'YOURPROJECT' is a placeholder (path parameter) in the URL that developers must replace with the actual project name or project ID for their environment. It will be pre-shared.

Generating an Access Token

To generate an OIDC access token from the Identity Access Management service, use the following API:

Endpoint:
POST https://auth.preprod.parking.scheidt-bachmann.net/auth/realms/YOURPROJECT/protocol/openid-connect/token

Request Parameters

	Params	Values
Header	Content-type	application/x-www-form-urlencoded
Body	client_secret	Your secret for the project
Body	grant_type	client_credentials
Body	client_id	Your client ID for the project

Example Request

curl -X POST \
  https://auth.preprod.parking.scheidt-bachmann.net/auth/realms/YOURPROJECT/protocol/openid-connect/token \
  -H 'Content-type: application/x-www-form-urlencoded' \
  -d 'client_id=your_client_id&client_secret=your_client_secret&grant_type=client_credentials'

Example Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJfT...",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI...",
  "token_type": "bearer",
  "not-before-policy": 0,
  "session_state": "a856fb91-eabc-4567-8765-ae8c24a6b111",
  "scope": "email profile"
}

Using the Access Token

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

curl -X GET \
  https://pm.preprod.parking.scheidt-bachmann.net/customers-contracts/v2/YOURPROJECT/customers \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJfT...'

Token Lifecycle

• Access tokens are valid for a limited time (typically 5 minutes as indicated by the expires_in field in the response)
• When an access token expires, you can use the refresh token to obtain a new access token without requiring the user to log in again
• Refresh tokens have a longer lifetime (typically 30 minutes as indicated by the refresh_expires_in field)

Refreshing an Access Token

To refresh an access token using a refresh token:

curl -X POST \
  https://auth.preprod.parking.scheidt-bachmann.net/auth/realms/YOURPROJECT/protocol/openid-connect/token \
  -H 'Content-type: application/x-www-form-urlencoded' \
  -d 'client_id=your_client_id&client_secret=your_client_secret&grant_type=refresh_token&refresh_token=your_refresh_token'

Best Practices for Token Management

1. Store tokens securely: Never store tokens in client-side code or expose them to users
2. Implement token refresh: Automatically refresh tokens before they expire to maintain uninterrupted access
3. Handle token expiration: Implement proper error handling for expired tokens
4. Use appropriate scopes: Request only the scopes your application needs
5. Implement token revocation: Revoke tokens when they are no longer needed

Common Authentication Issues

401 Unauthorized

This error occurs when:

• The access token is missing
• The access token is invalid
• The access token has expired

Solution: Generate a new access token or refresh the existing one.

403 Forbidden

This error occurs when:

• The access token is valid, but the user does not have permission to access the requested resource
• The requested scope is not included in the token

Solution: Ensure the user has the appropriate permissions and the token includes the necessary scopes.

Security Considerations

1. Use HTTPS: Always use HTTPS for API requests to ensure tokens are transmitted securely
2. Implement proper error handling: Handle authentication errors gracefully
3. Monitor token usage: Implement logging and monitoring to detect suspicious token usage
4. Implement rate limiting: Protect your authentication endpoints from brute force attacks
5. Use short-lived tokens: Keep token lifetimes as short as practical for your application

By following these guidelines, you can securely authenticate with the entervo infinite API and protect your application and user data.