OAuth Apps

OAuth Apps

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

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

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	Events the user attends or created
bans:read	Ban or suspension status for the user

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

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"

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:

1. Generate a code_verifier (random base64url string).
2. Compute code_challenge = BASE64URL(SHA256(code_verifier)).
3. Send code_challenge and code_challenge_method=S256 on the authorize request.
4. 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:

1. Complete domain verification for your website and redirect URIs (required for sensitive configurations).
2. Open the Publishing page in your app settings.
3. Click Verify / Publish App to submit for staff review when required.
4. 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.

Related guides

• Developer Platform Overview
• Public API
• Webhooks