Authentication
YorAuth provides multiple authentication methods for your application's users, all accessible through a consistent REST API under your application's namespace.
How It Works
Every authentication endpoint is scoped to your application using the {applicationId} path parameter. This means user accounts, sessions, and credentials are fully isolated between applications.
All multi-tenant auth endpoints follow this base path:
https://api.yorauth.com/api/v1/applications/{applicationId}/users/...
Replace {applicationId} with your application's UUID, found in the YorAuth dashboard.
Authentication Methods
Email and Password
The classic approach. Users register with an email address and password, then log in with those credentials. Successful login returns a JWT access token and a refresh token.
Password strength is enforced at registration and on password change. Failed login attempts are tracked per email address — after 5 consecutive failures the account is locked for 15 minutes.
Read the Email and Password guide
Magic Links
Passwordless authentication. The user provides their email address and receives a one-time link valid for 15 minutes. Clicking the link (or submitting the token to the API) exchanges it for a full token pair — no password required.
Magic links also auto-verify a user's email address on first use.
Multi-Factor Authentication (TOTP)
An additional layer on top of email/password login. Users enroll an authenticator app (Google Authenticator, Authy, etc.) by scanning a QR code. On subsequent logins, after credentials are verified, a 6-digit time-based code is required to complete authentication.
MFA setup returns backup codes for account recovery if the authenticator app is lost.
Token Model
Regardless of which method the user authenticates with, the API returns the same token pair:
| Token | Format | Lifetime | Purpose |
|---|---|---|---|
access_token | RS256 JWT | 15 minutes | Authenticate API requests |
refresh_token | Opaque string (ref_...) | 7 days (30 with remember_me) | Obtain new access tokens |
Send the access token in the Authorization header on every API request:
Authorization: Bearer <access_token>
When the access token expires, use the refresh token to obtain a new pair without requiring the user to log in again. The refresh token is rotated on every use.
Read the Token Management guide
Session Management
Each refresh token represents a session. Users can view all active sessions, see device and IP information for each, and revoke individual sessions or all sessions at once.
Read the Session Management guide
Rate Limits
Authentication endpoints apply strict rate limits to protect against brute-force attacks:
| Endpoint | Limit |
|---|---|
POST /users/login | 10 per minute per IP |
POST /users/register | Configurable per application |
POST /users/magic-link | 3 per 5 minutes per email |
POST /users/password/forgot | 3 per 15 minutes per email |
POST /users/email/resend | 2 per minute per email |
POST /users/token/refresh | 10 per minute |
Rate-limited responses return 429 Too Many Requests with a Retry-After header.
All authentication endpoints are public — they do not require an API key or JWT. Your applicationId in the URL path is sufficient to scope requests to your application.