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.

This step-by-step guide walks through the full short-token flow: generate one programmatically, embed it via Custom Module, and resolve it on the receiving side.

​
Prerequisites

  • A valid MileApp bearer token (JWT). Get one from the Authentication flow.
  • A Custom Module configured in MileApp Settings with a URL field. See Settings → Custom Module → Add Custom Module.
  • An external service ready to receive the URL invocation and resolve the short token.

​
Step 1 — Embed {SHORT_TOKEN} in Custom Module URL

When configuring or editing a Custom Module, use the {SHORT_TOKEN} placeholder anywhere in the URL string: 
https://my-service.example/webhook?token={SHORT_TOKEN}
Custom Module Add dialog with {SHORT_TOKEN} placeholder in URL field

The Add/Edit Custom Module dialog at Settings → Custom Module. Place {SHORT_TOKEN} wherever your external service expects the credential. Hover the info icon next to the URL label for a quick reminder.

When MileApp invokes this URL, it auto-generates a fresh short token (5-minute TTL) and substitutes the placeholder before sending.
You do not need to call POST /short-token/generate yourself for the Custom Module use case. MileApp handles generation server-side at invocation time.The Generate endpoint is intended for cases where your own application needs to mint a short token to pass to another system — see Step 2 below.

​
Step 2 — Generate Short Token Programmatically (advanced)

If you need to mint a short token outside the Custom Module context (e.g., in your own integration code), call the Generate endpoint with the current bearer token: 
curl -X POST "https://apiweb.mile.app/api/v3/short-token/generate" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
Response: 
{
  "status": true,
  "message": "Success.",
  "data": {
    "shortToken": "abc123def456ghi789",
    "expiresAt": 1705732800
  }
}
  • shortToken — opaque string, ~18 characters. Embed in URL or pass to downstream service.
  • expiresAt — Unix timestamp. After this moment, resolve will return 400.

​
Step 3 — Receive and Resolve

When your external service receives a URL with the short token, immediately resolve it: 
curl -X POST "https://apiweb.mile.app/api/v3/short-token/resolve" \
  -H "Content-Type: application/json" \
  -d '{"shortToken": "abc123def456ghi789"}'
Response: 
{
  "status": true,
  "message": "Success.",
  "data": {
    "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
    "userId": "6804ef87fff429d06900a937",
    "organizationId": "6804ef87fff429d06900a932"
  }
}
Use the returned bearerToken in subsequent calls back to MileApp APIs (e.g., to update a task on behalf of the user). Use userId and organizationId for authorization decisions on your own side.

​
Step 4 — Handle Failure Cases

The resolve endpoint returns 400 Bad Request when:
  • Short token has expired (more than 5 minutes since generation)
  • Short token never existed (typo, tampering, replay attack)
  • Short token format is malformed
Treat any 400 as an unauthenticated request. Reject the operation and respond to MileApp accordingly. Do not retry — the token is gone. 
{
  "status": false,
  "message": "Short token is invalid or expired"
}

​
Security Considerations

  • Treat short token as you would a password. Don’t log it, don’t send it in error reports, don’t store it.
  • TLS only. All calls to apiweb.mile.app are HTTPS. Don’t extract short tokens from any plaintext channel.
  • Resolve once, immediately. Don’t queue resolves. Don’t share short tokens across services.
  • Bearer token returned by resolve is the user’s real bearer. Treat the bearer with normal JWT precautions — limit blast radius, log access, etc.