> This page is for API Reference.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://fiftytwo-demo.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fiftytwo-demo.ferndocs.com/_mcp/server.

# About the Auth API

The 52VIKING AuthAPI provides authentication and token management for all
52ViKING systems and applications. **All 52 Cloud API requests require
authentication through it.**

Base URL: `https://auth.fiftytwo.com`

## Two methods

| Method              | Endpoint           | Purpose                                                          |
| ------------------- | ------------------ | ---------------------------------------------------------------- |
| User authentication | `POST /v1/user`    | Obtain an access token (AT) and refresh token (RT) via login     |
| Token refresh       | `POST /v1/refresh` | Exchange the token pair for new tokens without re-authenticating |

## Token lifetimes

| Token              | Valid for  |
| ------------------ | ---------- |
| Access token (AT)  | \~24 hours |
| Refresh token (RT) | \~30 days  |

Both are JWTs carrying an `exp` claim (a Unix timestamp), so you can read the
exact expiry locally. Decode it rather than waiting for a `401`.

In most cases a single access token covers all of a day's integration traffic.

## Workflow

#### Obtain AT and RT

`POST /v1/user` with username and password.

#### Send the AT on every request

`Authorization: Bearer YOUR_ACCESS_TOKEN`

#### Refresh when it expires

Either track the `exp` claim, or treat a `401` as the signal, then
`POST /v1/refresh` with the token pair.

#### Sign in again if refresh fails

The session is gone; start over at `/v1/user`.

## Best practices

> **Warning**
>
> **Do not call `/v1/user` for each request.** Sign-ins are rate limited to 15 per
> 60 seconds and will return `429 Too Many Requests`. Cache the access token.

* Use the AT for all API calls; refresh only on `401`.
* Both tokens sent to `/v1/refresh` must belong to the same user session.
* A `401` can also mean **insufficient privileges**. If a refresh succeeds but the
  call still fails, check the account's permissions instead of retrying.

## Next

#### [Authentication guide](/docs/authentication)

Copy-paste examples in cURL, Python, and TypeScript, plus a token-refresh loop.