> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/how-the-apps-work/screens/account/account-access.md).

# Account access

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). Platforms: web. [Source on GitHub](https://github.com/snapfix/docs/blob/main/spec/screens/account/account-access.md).
{% endhint %}

The web page that opens a link from an email or text message. It reads the link, signs the person in when the link allows it, or sends them on to choose a password. It shows only a spinner while it works.

* **Where:** web `/account-access?ctx=123`. The [Deep link](https://docs.snapfix.com/how-the-apps-work/screens/account/deep-link.md) page sends desktop browsers, and browsers that set `hasWebView`, here.
* **Who:** anyone with a link. The route has no guard, so it also runs for a signed-in browser.
* **Feature:** [Email and SMS links](https://docs.snapfix.com/product/features/account/email-links.md)

Checked live with an unknown link ID only; a real link comes by email or text \[[ASK-30](https://github.com/snapfix/docs/blob/main/ASK.md#ask-30-can-the-live-pass-reach-the-code-and-link-screens)]. The first request and the alert ran live: `GET /dl-ctx/{id}`, then the server's alert. The other steps are from code.

```mermaid
flowchart TD
  open["Open /account-access with ctx"] --> hasctx{"ctx present"}
  hasctx -->|no| err["Alert, then sign-in"]
  hasctx -->|yes| link["GET dl-ctx for the link"]
  link -->|"not ok"| err
  link -->|"ok"| ident{"email or phone in the link"}
  ident -->|no| err
  ident -->|yes| val["POST validate-username-v3 with the link"]
  val -->|"not ok, or no user"| err
  val -->|"verify_profile, or no temporary password"| fix["Signed in, go to /fix"]
  val -->|"otherwise"| setpw["Go to /auth/set-password"]
```

![Account access with an unknown link: the server's alert "invalid reference"](https://3653879137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVVGa79QbcEkJ7n8srxe%2Fuploads%2Fgit-blob-d5e4c9b9b7077e0cc66624163d84b718012404a4%2Faccount-access.jpg?alt=media)

## Layout

A centred loading spinner and nothing else: no title, no form and no button. When something fails, the alert appears over the grey background (see the screenshot).

## Inputs

| Field             | Type                | Required | Default | Rules and messages                                                                                                                                                        |
| ----------------- | ------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ctx` (URL query) | Text: the link's ID | Yes      | None    | Missing: "Something went wrong", then [Sign in](https://docs.snapfix.com/how-the-apps-work/screens/account/sign-in.md). The page passes the value to the server as it is. |

The email or phone number comes from the link's record on the server, not from the page.

## Actions

The page has no buttons. It runs these steps in order:

| Step                | What happens                                                                                                                                                                                                                                                                                                                                                            | API                                                                                                   |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Read the link       | Asks the server about the link, with no error alert of its own. The server counts each open; what else it does depends on the link type (below).                                                                                                                                                                                                                        | [`GET /dl-ctx/{id}`](https://docs.snapfix.com/engineering-reference/api/auth.md) on authpy            |
| Identify the person | Takes the email (`fUsername`), or, when the link has both a phone number and a country code, the phone's digits with one leading 0 removed. The country code itself is not sent.                                                                                                                                                                                        | -                                                                                                     |
| Check the contact   | Asks the server to check that contact with this link, and to return tokens for the account.                                                                                                                                                                                                                                                                             | [`POST /validate-username-v3`](https://docs.snapfix.com/engineering-reference/api/auth.md) with `ctx` |
| Sign in             | For a `verify_profile` link, or a user whose `temp_password` and `temp_password_required` are both 0: stores the tokens and the user and opens `/fix`.                                                                                                                                                                                                                  | -                                                                                                     |
| Choose a password   | Otherwise opens `/auth/set-password` with the user ID, the link, the access token and the whole check answer: [Accept invitation](https://docs.snapfix.com/how-the-apps-work/screens/account/accept-invitation.md) for a `user-invitation` link, [Reset your password](https://docs.snapfix.com/how-the-apps-work/screens/account/reset-password.md) for anything else. | -                                                                                                     |

A second start while the steps run is ignored.

**What the server does with the link** ([Auth API](https://docs.snapfix.com/engineering-reference/api/auth.md)):

* Every open counts (`count_opened`).
* A `reset_password` link that is unused and less than 15 minutes old marks the account's password as temporary. Older links answer "reference expired"; used ones "invalid reference".
* A `verify_profile` link runs the stored sign-up and creates the account when it is opened, before the person signs in.
* A `user-invitation` link for a pending invitation is marked as onboarded and counted as used during the contact check. That check also requires that the invitation was sent to this account.
* A `qrcode-invitation` link returns no person, so this page shows "Something went wrong" and opens sign-in; the apps open sign-up instead ([Sign up by QR invitation](https://docs.snapfix.com/how-the-apps-work/screens/account/qr-sign-up.md)).
* The same route also accepts expired sign-in tokens on its token path. The web does not use that path; it sends the shared login.

For link types other than invitations, the contact check returns tokens for the email or phone the page sends; whether it ties the link to that account was not settled in this merge.

## States

* **Loading:** the spinner, until the checks finish.
* **Empty:** not applicable.
* **Error:** an alert with an error icon; its "OK" opens [Sign in](https://docs.snapfix.com/how-the-apps-work/screens/account/sign-in.md). The text is the link answer's message, or "Something went wrong" when there is none, when the link has no email or phone, or when the contact check fails. A refused contact check shows the server's message in the shared alert as well. For an unknown link the server's text is "invalid reference", in English and lower case (checked live).
* **No permission:** not applicable; the page is public. Signed in, the same alert appears over the app's page, and "OK" lands on `/fix/groups` because the sign-in route sends a signed-in user on (checked live).
* **Offline:** the requests fail and the "Something went wrong" alert shows.

## Dialogs and sheets

* **Error alert:** see [States](#states).

## Platform differences

* **Web only.** The apps open the same links themselves; the steps are in [Sign in](https://docs.snapfix.com/how-the-apps-work/screens/account/sign-in.md), [Reset your password](https://docs.snapfix.com/how-the-apps-work/screens/account/reset-password.md), [Accept invitation](https://docs.snapfix.com/how-the-apps-work/screens/account/accept-invitation.md) and [Sign up by QR invitation](https://docs.snapfix.com/how-the-apps-work/screens/account/qr-sign-up.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/how-the-apps-work/screens/account/account-access.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
