Skip to content
flinkeyflinkey for Developers

Authentication

Authentication is a backend responsibility. Your backend uses API Manager credentials to obtain an OAuth access token, which is then sent as a bearer token on all protected API requests.

Required configuration

Section titled “Required configuration”
FLINKEY_API_BASE_URL=https://api-uat.flinkey.de/v3
FLINKEY_API_KEY=<from flinkey Portal>
FLINKEY_API_MANAGER_USERNAME=<from flinkey Portal>
FLINKEY_API_MANAGER_PASSWORD=<from flinkey Portal>

All values must come from environment variables or a secret manager — never hardcode them.

Authentication flow

Section titled “Authentication flow”

  1. Read credentials from environment variables at startup. Fail fast if any required value is missing.

  2. Request an access token by calling POST /oauth2/token with:

    • flinkey-API-Key header
    • API Manager username and password in the request body (grant_type=password)

  3. Store the token in backend memory or a secure backend cache. Never persist tokens to disk or logs.

  4. Attach the token to all protected API requests:

    Authorization: Bearer <access_token>
    flinkey-API-Key: <your_api_key>

  5. Refresh the token before it expires. If a request returns 401, refresh the token and retry once.

Token lifecycle

Section titled “Token lifecycle”
stateDiagram-v2
    [*] --> Unauthenticated
    Unauthenticated --> TokenRequested
    TokenRequested --> Authenticated: token received
    TokenRequested --> AuthenticationFailed: invalid credentials
    Authenticated --> TokenExpired: token expires
    TokenExpired --> TokenRequested: refresh
    AuthenticationFailed --> [*]

Error handling

Section titled “Error handling”
Error Cause Action
Missing environment variable Configuration incomplete Fail startup or mark integration unhealthy
Invalid API Manager credentials Wrong username/password Raise configuration error — do not retry endlessly
Invalid API key Wrong flinkey-API-Key Raise configuration error
Token endpoint unavailable Network/service issue Retry with exponential backoff
Token expired Normal lifecycle Refresh token, retry original request once

Security rules

Section titled “Security rules”
  • Read all credentials from environment variables or a secret manager.
  • Separate UAT and PROD credentials strictly.
  • Use short-lived access tokens as intended.
  • Never log credentials, bearer tokens or API keys.
  • Mask sensitive values in diagnostics and error messages.

Next steps

Section titled “Next steps”