Appearance

Authentication ​

The Brunago API uses Bearer tokens for authentication. All protected endpoints require a valid token in the Authorization header.

Getting Started ​

Obtain a Token ​

To get a Bearer token, register or login:

Both registration and login endpoints return a token in the response:

json
{
  "token": "3|4UgEk8lXwa1D6rbYO8fqMfKhgnwdRuSqZb4Woz083ad0785f"
}

Use the Token ​

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

http
GET /api/v1/me HTTP/1.1
Host: api.brunago.sk
Authorization: Bearer 3|4UgEk8lXwa1D6rbYO8fqMfKhgnwdRuSqZb4Woz083ad0785f
Accept: application/json

Example with cURL:

bash
curl --request GET \
  --url https://api.brunago.sk/api/v1/me \
  --header 'Authorization: Bearer 3|4UgEk8lXwa1D6rbYO8fqMfKhgnwdRuSqZb4Woz083ad0785f' \
  --header 'Accept: application/json'

Token Management ​

Token Lifecycle ​

  • Creation: Tokens are created during registration or login
  • Storage: Store tokens securely in your application (e.g., secure storage, HttpOnly cookies)
  • Revocation: Tokens are revoked during logout
  • Expiration: Tokens do not expire automatically but are single-device tokens

Logout ​

To revoke a token and end the session:

http
POST /api/v1/auth/logout
Authorization: Bearer {your-token}

See Logout for details.

Error Responses ​

401 Unauthorized ​

When authentication is missing or invalid:

json
{
  "message": "Unauthenticated."
}

Common Causes:

  • Token not included in Authorization header
  • Invalid or malformed token
  • Token has been revoked (logged out)
  • Incorrect header format (must be Bearer {token})

403 Forbidden ​

When authenticated but not authorized for the action:

json
{
  "message": "Access denied for authenticated users."
}

Common Causes:

  • Wrong user role (e.g., client trying to access expert-only endpoint)
  • Attempting to access another user's resources
  • Accessing an endpoint while already authenticated (e.g., registration)

Security Best Practices ​

Token Security

  • Never expose tokens in URLs, logs, or client-side code
  • Use HTTPS for all API requests to prevent token interception
  • Store securely in secure storage or HttpOnly cookies
  • Implement timeout on client side for inactive sessions
  • Handle 401 errors by redirecting to login

Role-Based Access ​

The API has two user roles with different capabilities:

Client Role ​

  • Create testimonies
  • View and accept offers
  • Make payments
  • Download completed testimonies

Expert Role ​

  • View available testimonies
  • Create offers
  • Upload completed testimonies
  • Manage professional profile

See User Object for role details.

Common Authentication Patterns ​

Initial Registration ​

javascript
// Register new client
const response = await fetch('/api/v1/auth/register/client', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'client@example.com',
    password: 'SecurePass123',
    // ...other fields
  })
});

const { token } = await response.json();
// Store token securely (e.g., secure cookie, native secure storage)

Authenticated Request ​

javascript
// Make authenticated request
const token = getStoredToken(); // retrieve from secure storage

const response = await fetch('/api/v1/me', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Accept': 'application/json'
  }
});

Handle 401 Error ​

javascript
// Automatically redirect to login on 401
fetch('/api/v1/protected-endpoint', {
  headers: { 'Authorization': `Bearer ${token}` }
})
.then(response => {
  if (response.status === 401) {
    // Token invalid - redirect to login
    window.location.href = '/login';
  }
  return response.json();
})