Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mileapp.dev/llms.txt

Use this file to discover all available pages before exploring further.

Short Token is a security mechanism that lets you embed an authentication context in URLs without exposing your bearer token. It addresses a class of token-exposure issues that arise when MileApp invokes external services on your behalf ā€” for example, when a Custom Module URL calls a third-party endpoint that needs to know who the user is.
Custom Module URL field with {SHORT_TOKEN} placeholder and explanation tooltip

Inside the Add/Edit Custom Module dialog, the URL field accepts the {SHORT_TOKEN} placeholder. Hover the info icon next to the URL label to read the inline reminder.

ā€‹
Why Short Token?

Embedding a bearer token directly in a URL (e.g., https://my-service.example/webhook?token=eyJhbGc...) exposes the credential to:
  • External service logs ā€” your URL is logged on the receiving server.
  • Browser history ā€” if a user pastes the rendered URL anywhere.
  • Network monitoring ā€” intermediaries may capture the query string.
Once exposed, the bearer token is valid for the rest of its lifetime ā€” typically hours. An attacker who reads any of the above can impersonate the user during that window. Short Token replaces that pattern. Instead of embedding the bearer, you embed a one-time placeholder. MileApp generates a short-lived token (5-minute TTL) on the fly, your external service receives it, and exchanges it back for the bearer token via a dedicated API.

ā€‹
How It Works

  1. Configure Custom Module URL with the {SHORT_TOKEN} placeholder:
https://my-service.example/webhook?token={SHORT_TOKEN}
  1. MileApp invokes the URL. Before sending, MileApp generates a fresh short token (5 min TTL) and substitutes the placeholder. Your service receives:
https://my-service.example/webhook?token=abc123def456ghi789
  1. Your service resolves the short token via the public API:
POST https://apiweb.mile.app/api/v3/short-token/resolve
Content-Type: application/json

{ "shortToken": "abc123def456ghi789" }
  1. The response includes the original bearerToken plus userId and organizationId. Use them to authorize the request on your side.
  2. If the short token has expired (after 5 minutes) or is invalid, the resolve endpoint returns 400. Treat this as an unauthenticated request.

ā€‹
Constraints

  • TTL: 5 minutes. Plan your external service to resolve the short token promptly on receipt, not asynchronously.
  • Single-use, single-context. Each short token resolves to exactly one bearer/user/org. Resolving it twice may still return data (no strict single-use guarantee), but never assume re-use is reliable.
  • No authentication required for resolve. The short token itself is the credential. Treat it like a one-time password ā€” short-lived, sensitive, and never reused for logging.