Ysra Docs

Authentication

Exchange an email and password for a bearer token, and use it on every request to the Ysra API.

On this page

The API authenticates requests with a signed bearer token. Tokens are valid for 24 hours by default.

Sign in#

POST /auth/login

Exchange credentials for an access token.

Request body#

email string required
The account's email address.
password string required
The account's password.

Response#

access_token string
The bearer token. Send it as Authorization: Bearer <token>.
token_type string
Always bearer.
user object
id, email, name and is_admin for the signed-in account.
$ curl -sS "$YSRA_API_URL/auth/login" \
    -H 'content-type: application/json' \
    -d '{"email": "you@example.com", "password": "…"}'

import httpx

response = httpx.post(
    f"{api_url}/auth/login",
    json={"email": "you@example.com", "password": password},
)
response.raise_for_status()
token = response.json()["access_token"]

const response = await fetch(`${apiUrl}/auth/login`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ email: "you@example.com", password }),
});
if (!response.ok) throw new Error(`Sign-in failed: ${response.status}`);
const { access_token: token } = await response.json();
200 OK
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "token_type": "bearer",
  "user": {
    "id": "5b0d3c1e-…",
    "email": "you@example.com",
    "name": "Ada",
    "is_admin": false
  }
}

Errors#

Status When
401 The email or password is wrong.
422 The body is not valid — for example, a malformed email.

The current account#

GET /auth/me

Returns the account the token belongs to. Useful to validate a stored token on startup: a 401 means sign in again.

Keeping tokens safe#

  • Keep tokens on servers or in platform secure storage. A token in a mobile binary or a public repository is compromised.
  • Treat 401 from any route as "sign in again", not as a permanent failure.
  • On shared machines, POST /auth/logout ends the session.
YsraDocs