Authentication API

The authentication API provides OAuth 2.0 token endpoints for user authentication.

Endpoints

---

Get Access Token

POST /api/v1/login/oauth/access_token

Authenticate a user and receive access and refresh tokens.

Request Body (form-urlencoded)

Parameter	Type	Required	Description
grant_type	string	Yes	Either password or refresh_token
username	string	Conditional	Required for password grant. User's email address
password	string	Conditional	Required for password grant. User's password
refresh_token	string	Conditional	Required for refresh_token grant

Password Grant Example

cURLJavaScriptPython

curl -X POST https://api.usetotis.com/api/v1/login/oauth/access_token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "[email protected]" \
  -d "password=mypassword"

const response = await fetch('https://api.usetotis.com/api/v1/login/oauth/access_token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
    grant_type: 'password',
    username: '[email protected]',
    password: 'mypassword',
  }),
});

const tokens = await response.json();

import requests

response = requests.post(
    'https://api.usetotis.com/api/v1/login/oauth/access_token',
    data={
        'grant_type': 'password',
        'username': '[email protected]',
        'password': 'mypassword',
    }
)

tokens = response.json()

Refresh Token Example

cURL

curl -X POST https://api.usetotis.com/api/v1/login/oauth/access_token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN"

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response Fields

Field	Type	Description
access_token	string	JWT access token for API requests
token_type	string	Always bearer
expires_in	integer	Token validity in seconds (3600 = 1 hour)
refresh_token	string	Token for obtaining new access tokens

Error Responses

Status	Error	Description
401	INVALID_CREDENTIALS	Wrong username or password
401	INVALID_GRANT	Invalid refresh token
400	UNSUPPORTED_GRANT_TYPE	Invalid grant_type value

---

Token Usage

Include the access token in all authenticated requests:

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

Token Refresh Strategy

Best Practice

Implement automatic token refresh in your application. When you receive a 401 response, attempt to refresh the token before retrying the request.

async function apiRequest(url, options = {}) {
  let response = await fetch(url, {
    ...options,
    headers: {
      ...options.headers,
      'Authorization': `Bearer ${accessToken}`,
    },
  });

  if (response.status === 401) {
    // Try to refresh the token
    const newTokens = await refreshAccessToken();
    accessToken = newTokens.access_token;

    // Retry the request
    response = await fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${accessToken}`,
      },
    });
  }

  return response;
}