# Sign in app users through the API

> Call the REST API with only an API key, or sign an app user in so calls act as that user and row-level security applies. Covers tokens and magic links.

Source: https://tadabase.com/docs/developers/authentication-methods  
Status: Verified Nov 17, 2026. Checked against the current product

A REST API call can run in two ways: with only the API key, as the app owner, or as one of the app's users after signing them in. Sign a user in when your integration acts for that person, such as a mobile app or a custom portal, and should see only what they may see.

## Key only, or as an app user

|  | API key only | API key plus a user token |
| --- | --- | --- |
| Headers | `X-Tadabase-App-Key`, `X-Tadabase-App-Secret` (and `X-Tadabase-App-id` on v1) | The same, plus `Authorization: Bearer {token}` |
| Acts as | The app owner, limited by the key's permissions | The signed-in user, and still limited by the key's permissions |
| Row-level security | Not applied: the call sees every record | Applied, on tables whose row-level security covers the classic app and REST API |
| Use it for | Server-to-server sync, reports, back-office scripts | Apps and portals where a person signs in |

Both ways need a valid API key: a user token on its own is not enough. Keep the key's secret on your server in both cases.

## Sign a user in

User sign-in is on API v1.1, which has the app ID in the URL. Send the user's email and password:

```bash
curl -X POST "https://api.tadabase.io/api/v1.1/$TADABASE_APP_ID/auth/login" \
  -H "X-Tadabase-App-Key: $TADABASE_APP_KEY" \
  -H "X-Tadabase-App-Secret: $TADABASE_APP_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"email": "dana@example.com", "password": "their password"}'
```

```json
{
  "token": "eyJpdiI6...",
  "user_id": "DVWQWRNZ49",
  "expires_at": "2026-11-17 22:30:00",
  "logged_in_since": "2026-11-17 10:30:00",
  "status": "success"
}
```

Send the token on later calls in `Authorization: Bearer {token}`, together with the key headers. It works on both v1 and v1.1 calls.

- **How long a token lasts**: 12 hours by default. To choose, send `remember` with a number of minutes in the login body. Times in the response are in UTC; `expires_at` is when the token stops working.
- **Same rules as the app's login**: the sign-in is refused if the user's email domain is not allowed, if the app only allows single sign-on, or if the app's login rules turn the user away. If the app blocks users after failed sign-ins, a blocked user or IP address is refused with a 429 error.
- A failed sign-in returns `"status": "error"` with a `msg`, such as "Email or password entered is incorrect."
- A sign-in through the API starts the same workflows as a user logging in to the app.

## Check or end a token

| Call | What it does |
| --- | --- |
| `POST /api/v1.1/{appId}/auth/status` | Tells you whether the token still works. A valid token returns `"status": "success"` with `expires_at`, `logged_in_since` and `user_id`; otherwise `"status": "error"` and "User token expired." `auth/heartbeat` does the same. |
| `POST /api/v1.1/{appId}/auth/logout` | Ends the token: it stops working at once. Returns "You have successfully logged out." |

Send the key headers and `Authorization: Bearer {token}` with both. When a token has expired, sign the user in again.

## What a call as a user sees

With a user token, record calls follow the row-level security of each table, as long as the table's **Where these rules apply** setting is **Classic app & REST** or **Everywhere**. Tables set to **API, Vibe & AI** only are not filtered for REST API calls. See [Row-level security](https://tadabase.com/docs/get-started/row-level-security).

- A filter or sort on a field the user may not read is refused with a 403 error.
- A batch update on a table whose row-level security applies is refused for a user token, because it cannot check the user's rules record by record. Run it with the key only, as the owner.
- A token that cannot be read is treated as a sign-in that failed, never as a key-only call: a call meant for a user never sees more than that user would.

> **The key alone sees everything:** A call with only the API key ignores row-level security. Never use it to serve data to a person who should see only their own records; sign them in instead.

## Create a magic link

A magic link signs a user into the live app from a link, without a password. To create one through the API, the API key needs a magic link chosen under **Magic Link** in its settings, and your plan must include magic links in the API.

```bash
curl -X POST "https://api.tadabase.io/api/v1.1/$TADABASE_APP_ID/auth/magic-link" \
  -H "X-Tadabase-App-Key: $TADABASE_APP_KEY" \
  -H "X-Tadabase-App-Secret: $TADABASE_APP_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"email": "dana@example.com"}'
```

| Body field | What it does |
| --- | --- |
| `email` or `user_id` | The user to sign in. Send one of them. |
| `redirect_url` | Optional. Where the user lands after signing in. |
| `redirect_page_id` | Optional. The page the user lands on. |
| `redirect_detail_page_id` and `detail_record_id` | Optional. Open a details page for one record. |
| `2fa_email_template_id` | Optional. The email template for the second sign-in step, if the magic link asks for one. |

The response has `"status": "success"`, the `token` and the full link in `magicLinkUrl`. If the key has no magic link chosen, the call is refused with "The method being used is disabled for this API key."; if no such user exists, with "User not allowed." See [Magic links](https://tadabase.com/docs/users-security/magic-links) for how the link behaves.

## Try it in the API Playground

In the [API Playground](https://tadabase.com/docs/developers/api-playground), set **Call as** to **A signed-in app user** and sign in with a test user's email and password, or paste a token from `auth/login` and click **Use token**. Every request then runs as that user. The token stays in the page and is never saved.
