OAuth Apps

Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.

OAuth apps let users sign in to your application with their TrucklineMP account. After authorization, your app receives access tokens scoped to the permissions you requested.

OAuth is separate from Public API keys. Use OAuth when you need to act on behalf of a signed-in user. Use API keys for server-side reads of public platform data.

Create an app

Enable Developer Mode and open the Developer Console.
Go to OAuth Apps and click Create App.
Fill in the app name, description, icon, website, and legal URLs.
On the OAuth page, set redirect URIs (one per line) and select scopes.
Save changes. Copy the client secret when it is shown. It cannot be retrieved later.

Redirect URI rules

Exact match is required at authorize and token time (including path, port, and trailing slash).
https:// public hosts are allowed.
http:// is allowed only for local development hosts: localhost, *.localhost, 127.x.x.x, private LAN ranges (10/8, 172.16/12, 192.168/16), and host.docker.internal.
Custom app schemes are allowed for native clients (for example myapp://callback).
Fragments (#...) and embedded credentials (user:pass@) are rejected.

App types

Type	Client secret	Typical use
confidential (default)	Required at the token endpoint	Server-side web apps and backends
public	Not used	Mobile apps and SPAs that use PKCE

Public clients authenticate at the token endpoint with client_secret_post omitted. Confidential clients must send client_secret.

OAuth endpoints

Discovery document (OAuth 2.0 Authorization Server Metadata):

GET https://trucklinemp.com/.well-known/oauth-authorization-server

Endpoint	URL
Authorization	`https://trucklinemp.com/oauth/authorize`
Token	`https://trucklinemp.com/api/oauth/token`
Revocation	`https://trucklinemp.com/api/oauth/revoke`
Userinfo	`https://trucklinemp.com/api/oauth/userinfo`

Supported response type: code (authorization code flow).

Supported grant types: authorization_code, refresh_token.

Supported PKCE method: S256.

Scopes

Scope	Access
`profile`	Username, avatar, and public profile (required)
`vtc:read`	VTC membership, roles, and VTC details
`events:read`	Reserved for future userinfo fields (not returned yet)
`bans:read`	Reserved for future userinfo fields (not returned yet)

Request only the scopes your app needs. Users see the full list on the consent screen.

events:read and bans:read can be requested today but do not add fields to userinfo yet. Use the Public API ban endpoints for public ban data instead.

Authorization flow

1. Redirect the user to authorize

Build a URL (or use the install link on your app overview):

https://trucklinemp.com/oauth/authorize
  ?client_id=tlmp_client_...
  &response_type=code
  &redirect_uri=https://your-app.com/callback
  &scope=profile vtc:read
  &state=RANDOM_CSRF_TOKEN

If your app requires PKCE, also include:

&code_challenge=CHALLENGE
&code_challenge_method=S256

Generate the challenge from a code_verifier using SHA-256 and base64url encoding.

2. User consents

The user signs in (if needed) and approves the requested scopes. TrucklineMP redirects back to your redirect_uri with code and state.

Verify state matches what you sent to prevent CSRF attacks.

3. Exchange the code for tokens

curl -X POST "https://trucklinemp.com/api/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=tlmp_client_..." \
  -d "client_secret=tlmp_secret_..." \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://your-app.com/callback" \
  -d "code_verifier=VERIFIER_IF_PKCE"

Response includes access_token (tlmp_...) and optionally refresh_token (tlmpr_...).

4. Call userinfo

curl -H "Authorization: Bearer tlmp_ACCESS_TOKEN" \
  "https://trucklinemp.com/api/oauth/userinfo"

Userinfo response

Fields depend on the scopes granted to the access token. The subject is always included.

Always returned

Field	Type	Description
`sub`	string	TrucklineMP user ID
`web_id`	string	Public WebID

With `profile` scope

Field	Type	Description
`name`	string	Display name
`picture`	string	Avatar URL
`handle`	string	Public `@handle` (may be null)
`steam_id`	string \| null	Linked SteamID64

With `vtc:read` scope

Field	Type	Description
`vtc_memberships`	array	Objects with `vtcId`, `vtcName`, `role`, `isOwner`, `joinedAt`

Example

{
  "sub": "user_abc123",
  "web_id": "10042",
  "name": "Driver Name",
  "picture": "https://cdn.example/avatar.webp",
  "handle": "drivername",
  "vtc_memberships": [
    {
      "vtcId": 7,
      "vtcName": "Example Logistics",
      "role": "Driver",
      "isOwner": false,
      "joinedAt": "2026-01-15T10:00:00.000Z"
    }
  ]
}

Invalid or expired tokens return HTTP 401 with { "error": "invalid_token" }.

PKCE

PKCE protects public clients that cannot store a client secret. Enable Require PKCE on your app’s security settings to reject authorization requests without a valid challenge.

When PKCE is required:

Generate a code_verifier (random base64url string).
Compute code_challenge = BASE64URL(SHA256(code_verifier)).
Send code_challenge and code_challenge_method=S256 on the authorize request.
Send code_verifier on the token request.

Testing mode and test users

New third-party apps start unpublished. While unpublished:

Only the app owner and test users can complete authorization.
Everyone else sees a message that the app is in testing mode.

Add test users on the General page of your app settings. Search for TrucklineMP users by name or handle. The test user list can also include email addresses that match the authorizing account.

This lets you develop and QA without exposing the app to all TrucklineMP users.

Publishing

When your app is ready for the public:

Complete domain verification for your website and redirect URIs (required for sensitive configurations).
Open the Publishing page in your app settings.
Click Verify / Publish App to submit for staff review when required.
After approval, use Publish App to make the app available to all users.

Published apps can be unpublished again from the same page. Unpublishing returns the app to testing mode restrictions.

Staff may reject an app with notes explaining what to fix. Address the feedback and resubmit.

Token formats

Item	Prefix / format
Client ID	`tlmp_client_...`
Client secret	`tlmp_secret_...`
Access token	`tlmp_...`
Refresh token	`tlmpr_...`

Rotate the client secret from the security page if it is compromised. Existing tokens may be invalidated depending on your rotation settings.

Security checklist

Use HTTPS redirect URIs in production.
Always validate the state parameter.
Use PKCE for public clients and browser-based apps.
Store client secrets and refresh tokens server-side only.
Request the minimum scopes required.