API Authentication

API Authentication

Overview

The SecuFile Go API uses JWT (JSON Web Token) authentication with MFA and SSO support. All protected routes require a valid Bearer token in the Authorization header.

Obtaining a Token

POST /api/v1/auth/login

Authentication by email and password.

Request:

{
  "email": "user@example.com",
  "password": "securePassword123"
}

Response (without MFA):

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 900,
  "token_type": "Bearer",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "role": "client_admin",
    "mfa_enabled": false
  }
}

Response (MFA required):

{
  "mfa_required": true,
  "user_id": "uuid"
}

POST /api/v1/auth/mfa/verify

TOTP MFA code verification.

Request:

{
  "user_id": "uuid",
  "code": "123456"
}

Response: Same format as the successful login above.

POST /api/v1/auth/sso

Login via SSO (Zitadel OIDC). The Python backend handles the complete OIDC flow and sends user information to this route.

Request:

{
  "provider": "zitadel",
  "external_id": "zitadel-user-id",
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "groups": ["client_admin"]
}

POST /api/v1/auth/register

New user registration with organization creation.

Request:

{
  "email": "admin@company.com",
  "password": "securePassword123",
  "first_name": "Admin",
  "last_name": "User",
  "company_name": "My Company",
  "plan_code": "pro",
  "payment_method_id": "pm_stripe_id"
}

POST /api/v1/auth/refresh

Access token refresh.

Request:

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

POST /api/v1/auth/forgot-password

Request password reset (sends an email).

{
  "email": "user@example.com"
}

POST /api/v1/auth/reset-password

Reset password using the token received by email.

{
  "token": "reset-token-from-email",
  "new_password": "newSecurePassword123"
}

Using the Token

All protected routes require the following header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

The token contains the following claims:

• sub: User ID (UUID)
• email: User email
• role: Role (superadmin, msp, client_admin, client_user)
• client_id: Associated client ID
• exp: Expiration date
• iss: Issuer (filesecure)

User Profile Endpoints

Service Tokens

For API-to-API integrations, SecuFile supports service tokens:

X-Service-Token: <service-token>

Service tokens are managed via the /api/v1/organizations/:org_id/service-tokens endpoints with scope-based access control:

Service Token Scopes

Service token routes are available under /api/v1/service/ with scope checks:

• file:download -- Download files
• file:upload -- Upload files
• file:list -- List files
• folder:list -- List folders