# Authentication

The sign-in authentication process is managed in the `authController`.

This method checks that:

* the user exists
* the correct password has been provided
* the account is active 
* the sign-in is not suspicious (see sections below for more information)

If these conditions are met, an auth token is generated and returned to the client along with a user object.

### Authentication Model

The authentication model is located in `/model` directory and contains several methods for encoding and decoding the JSON web token and also the [verify middleware](/gravity-server/rest-api.md) for protecting the API endpoints.

## Magic Sign-in Links

Users can sign in using their username or password, or via a magic link that sends a time-sensitive JWT for authentication.

## Suspicious Sign-In Attempts

Each sign-in attempt is stored in the login table along with the device, browser and IP address. On each login attempt, `authController.signin` checks this table for suspicious activity based on past behaviour. \
\
If the IP address, device or browser differs from what the user typically uses to sign in, they will be notified via email.

## Blocked Sign-In Attempts

If all three parameters (IP,  browser and device) differ from past behaviour. The user's account will be disabled and the sign-in attempt blocked. The user will then receive a magic sign-in link via email to sign-in and unlock their account.

## Check the Auth Status

The auth status of a user can be checked by making a GET request to `/api/auth`**.** This request is performed every time the app is loaded or reloaded.

This will return an object with the following values:

| Key                         | Value         | Description                                                             |
| --------------------------- | ------------- | ----------------------------------------------------------------------- |
| jwt\_token                  | true or false | determines if the user has an active JWT                                |
| <p></p><p>social\_token</p> | true or false | determines of the user has an active access token from a social network |
| subscription                | string        | returns the stripe subscription status                                  |
| accounts                    | array         | a list of the account IDs the user belongs too                          |
| account\_id                 | UUID          | the currently authenticated account id                                  |
| authenticated               | true or false | true if the user has an app JWT or social token                         |

## **Deleting Auth Tokens**

You can sign out the user and delete the auth tokens by making a DELETE request to `/api/auth`


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.usegravity.app/gravity-server/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.