Mobile App¶

The vScrawl mobile app (iOS/Android) talks to the same API as the web app — the same documents, workflows, signing, organization, and settings endpoints described throughout this reference. This page covers what's different on mobile: how it authenticates, how it resolves its server, and the handful of behaviors that don't exist on web.

App structure¶

Five bottom-tab sections, plus a drawer:

The drawer adds document status filters (All, Draft, Pending, Sent, Signed, Completed, Voided, Approved, Viewed) and a live Folders list.

The Organization tab is permission-gated: a user who isn't the org owner and has no granted modules gets a "no permission" message rather than the screen. Templates and Users tiles are individually gated on the TEMPLATES/USERS modules from the caller's role.

1. Authentication — direct bearer tokens, no session cookie¶

This is the biggest difference from the web app. Mobile does not use the redirect-based session-cookie flow (mechanism 1). It uses direct JWT bearer throughout — no cookie jar, no browser redirect, no PKCE.

POST /auth/v1/signin
Content-Type: application/json

{
  "grant_type": "PASSWORD",
  "username": "jane@example.com",
  "password": "Str0ng!Passw0rd"
}

Tokens are held in the device's secure storage, and every subsequent request carries Authorization: Bearer <accessToken>.

Two-factor: HTTP 202 signals "TOTP required"¶

If the account has 2FA enabled, the password call returns 202 Accepted rather than 200 — that status is the app's cue to prompt for a code and re-post to the same endpoint with a different grant type:

POST /auth/v1/signin
Content-Type: application/json

{
  "grant_type": "G_AUTHENTICATOR",
  "username": "jane@example.com",
  "password": "Str0ng!Passw0rd",
  "tOtp": 483920
}

Token refresh¶

The app sets a timer from the expires_in value and refreshes proactively before expiry, rather than waiting for a 401:

POST /auth/v1/signin
Content-Type: application/json

{ "grant_type": "REFRESH_TOKEN", "refreshToken": "eyJhbGciOiJSUzI1NiIs..." }

Google sign-in¶

Mobile obtains the Google ID token natively (no browser redirect) and exchanges it directly:

GET /auth/v1/signin/social/google?ott=<google-id-token>

Shown only when sso.enableGoogleAuth is true in app settings.

2. Deep-link guest signing¶

The single most mobile-specific endpoint. When a recipient taps a signing link on their phone and the app is installed, the OS hands the link to the app instead of the browser — the app then establishes a guest session itself.

sequenceDiagram
    participant OS as Phone OS
    participant App as Mobile App
    participant API

    OS->>App: Universal/App link with ?docCode=...
    App-->>App: Force-logout any existing session
    App->>API: GET /auth/v1/getGuestToken/{docCode}
    API-->>App: accessToken + refreshToken + workflowId
    App->>API: GET /user/v1/settings/profile
    App->>API: GET /workflow/v1/{workflowId}
    App->>API: GET /workflow/v1/{workflowId}/recipients

    opt Recipient has enforceIdentity = true
        App->>API: POST /workflow/v1/{workflowId}/identity/send-otp
        App->>API: POST /workflow/v1/{workflowId}/identity/verify-otp
    end

    App-->>App: Open document viewer

GET /auth/v1/getGuestToken/{docCode}

{
  "workflowId": 887,
  "userId": 1042,
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "tokenType": "Bearer",
  "expires_in": 3600
}

Same endpoint and semantics as Guest Signing on web — the difference is purely that the app redeems the code itself and stores the result as a normal session, tagged as a guest so it's purged on the next cold start. An expired or invalid code routes to a "link expired" screen.

3. Runtime configuration¶

Unlike the web app (fixed origin), the mobile app resolves its API host at runtime:

1. On cold start it pulls the base URL from Firebase Remote Config (base_url_dev / base_url_staging / base_url_prod, selected by build flavor), falling back to a compiled-in default per environment.
2. A user can override the host entirely from the Server Configuration screen. Before saving, the app validates the entered URL by calling, unauthenticated:

GET /admin/internal/health

This is the only admin-namespace call the app makes, and it's used purely as a reachability probe — nothing else from the back-office API is used.

Branding, feature flags, and locale come from the standard public settings call, which the app fetches at splash and uses to theme itself (primary color, app name, logos):

GET /auth/v1/app_settings

The response's branding field is a JSON string containing APP_BRANDING.primaryColor, which drives the app's theme at runtime. powerSurveyRecipientLimit gates the Power Survey recipient count.

4. Document capture¶

The app can create a document from the camera as well as from a file:

• Scan — the device's document scanner captures pages, the app compresses them and assembles a PDF client-side.
• Gallery / camera photo — same, via the image picker.
• File pick — a PDF straight off the device.

All three paths end in the same upload call as web (Documents → Upload) — there is no separate scanning endpoint. Limit is 25 MB, matching the server. A scanned multi-page document can approach that, so the app compresses pages before assembling the PDF.

One extra field: timeZone¶

Mobile uploads include a timeZone multipart field derived from the device, formatted as an IANA identifier plus offset:

timeZone: Asia/Karachi GMT+05

This is the only device-derived value the app sends to the backend.

5. Signatures¶

Two capture modes, both ending at the shared Settings → Signature Settings endpoint:

• Draw — a signature pad canvas, exported as a base64 PNG.
• Type — typed text rendered in a bundled handwriting font.

PUT /user/v1/settings/signatures
Content-Type: application/json

{
  "image": "data:image/png;base64,...",
  "initialImage": "data:image/png;base64,...",
  "digitalSignatures": { "source": "...", "csc": { "userName": "..." } }
}

6. Two-factor QR handling¶

GET /user/v1/settings/generateQR returns the QR image as on web, but the app decodes it on-device to extract the OTP secret rather than asking the user to scan it with a separate authenticator app. No extra endpoint involved.

What the mobile app does not do¶

Worth stating explicitly, since these are commonly assumed to exist:

Endpoint parity¶

Beyond the mobile-specific items above, the app uses the same endpoints documented elsewhere on this site:

• Dashboard — status counts and org counts
• Documents — list, upload, rename, delete, reorder, page images, download
• Folders — full folder CRUD and moving documents
• Sending & Signing — recipients, fields, commence, sign, approve, decline, history, evidence report, identity OTP, CSC signing
• Power Survey — child-workflow list and CSV export
• Organization — details, members, roles, business apps
• Templates — list, create, rename, use, download
• Settings — profile, signatures, notifications, security, locale, roles