Authentication¶

Totis uses OAuth 2.0 with JWT tokens for authentication. All API requests (except public endpoints) require a valid access token.

Obtaining Tokens¶

Password Grant¶

Exchange user credentials for an access token:

POST /api/v1/login/oauth/access_token

Request Parameters (form-urlencoded)

Parameter	Type	Required	Description
`grant_type`	string	Yes	Must be `password`
`username`	string	Yes	User's email address
`password`	string	Yes	User's password

Example Request

curl -X POST https://api.usetotis.com/api/v1/login/oauth/access_token \
  -d "grant_type=password" \
  -d "[email protected]" \
  -d "password=secret123"

Example Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyLWlkIiwiZXhwIjoxNjk5MDAwMDAwfQ.xxx",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "refresh-token-here"
}

Refresh Token Grant¶

Use a refresh token to obtain a new access token:

Request Parameters (form-urlencoded)

Parameter	Type	Required	Description
`grant_type`	string	Yes	Must be `refresh_token`
`refresh_token`	string	Yes	The refresh token

Example Request

curl -X POST https://api.usetotis.com/api/v1/login/oauth/access_token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=your-refresh-token"

Using Access Tokens¶

Include the access token in the Authorization header for all authenticated requests:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://api.usetotis.com/api/v1/user

Token Contents¶

The JWT access token contains:

Claim	Description
`sub`	User ID
`workspace_id`	Current workspace ID
`role`	User's role in the workspace
`exp`	Token expiration timestamp
`iat`	Token issued timestamp

Token Expiration¶

Token Type	Expiration
Access Token	1 hour
Refresh Token	30 days

Token Security

Never expose your tokens in client-side code, URLs, or version control. Store tokens securely and transmit them only over HTTPS.

Error Responses¶

Status Code	Error	Description
401	`UNAUTHORIZED`	Invalid or expired token
401	`INVALID_CREDENTIALS`	Wrong username or password
401	`TOKEN_EXPIRED`	Access token has expired

Public Endpoints¶

The following endpoints do not require authentication:

POST /api/v1/login/oauth/access_token - Token endpoint
POST /api/v1/onboarding/signup - User registration
GET /api/v1/verification/verify - Email verification
GET /api/v1/public/file/{publicLinkId}/{fileName} - Public file download
GET /api/v1/public/file/{publicLinkId}/qr - Public link QR code