Skip to main content

Authentication API

Authenticate and manage user sessions via the API.

Overview​

Sparbz Cloud supports multiple authentication methods:

  • JWT Token: For user sessions (browser, CLI)
  • API Key: For programmatic access (CI/CD, SDKs)
  • OAuth 2.0: For third-party integrations (GitHub, Google)

Authentication Headers​

JWT Token​

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

API Key​

Authorization: ApiKey szc_prod_abc123xyz...

Login​

Email/Password Login​

POST /v1/auth/login

Request Body:

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

Response:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": "2024-01-16T10:30:00Z",
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "name": "John Doe"
    }
  }
}

OAuth Login​

Initiate OAuth Flow​

GET /v1/auth/oauth/:provider

Providers: github, google

Query Parameters:

ParameterTypeDescription
redirect_uristringWhere to redirect after authentication
statestringCSRF protection token

Response: 302 Redirect to OAuth provider

OAuth Callback​

GET /v1/auth/oauth/:provider/callback

Query Parameters:

ParameterTypeDescription
codestringAuthorization code from provider
statestringCSRF protection token

Response: 302 Redirect to redirect_uri with token

Register​

POST /v1/auth/register

Request Body:

{
  "email": "newuser@example.com",
  "password": "secure-password",
  "name": "New User"
}

Response: 201 Created

{
  "data": {
    "user": {
      "id": "usr_new123",
      "email": "newuser@example.com",
      "name": "New User",
      "email_verified": false
    },
    "message": "Verification email sent"
  }
}

Verify Email​

POST /v1/auth/verify-email

Request Body:

{
  "token": "verification-token-from-email"
}

Response:

{
  "data": {
    "message": "Email verified successfully",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Forgot Password​

POST /v1/auth/forgot-password

Request Body:

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

Response:

{
  "data": {
    "message": "Password reset email sent"
  }
}

Reset Password​

POST /v1/auth/reset-password

Request Body:

{
  "token": "reset-token-from-email",
  "password": "new-secure-password"
}

Response:

{
  "data": {
    "message": "Password reset successfully"
  }
}

Refresh Token​

POST /v1/auth/refresh

Request Body:

{
  "refresh_token": "refresh-token-value"
}

Response:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": "2024-01-16T10:30:00Z"
  }
}

Logout​

POST /v1/auth/logout

Invalidates the current session token.

Response: 204 No Content

Current User​

Get Current User​

GET /v1/auth/me

Response:

{
  "data": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "name": "John Doe",
    "avatar_url": "https://avatars.sparbz.cloud/usr_abc123.png",
    "email_verified": true,
    "two_factor_enabled": false,
    "organizations": [
      {
        "id": "org_abc123",
        "name": "Acme Corp",
        "role": "owner"
      }
    ],
    "current_organization_id": "org_abc123",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Update Current User​

PATCH /v1/auth/me

Request Body:

{
  "name": "John Smith",
  "avatar_url": "https://example.com/avatar.png"
}

Response:

{
  "data": {
    "id": "usr_abc123",
    "name": "John Smith",
    "avatar_url": "https://example.com/avatar.png"
  }
}

Two-Factor Authentication​

Enable 2FA​

POST /v1/auth/2fa/enable

Response:

{
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "qr_code_url": "data:image/png;base64,...",
    "backup_codes": [
      "abc123",
      "def456",
      "ghi789"
    ]
  }
}

Confirm 2FA​

POST /v1/auth/2fa/confirm

Request Body:

{
  "code": "123456"
}

Response:

{
  "data": {
    "two_factor_enabled": true
  }
}

Disable 2FA​

DELETE /v1/auth/2fa

Request Body:

{
  "code": "123456"
}

Response: 204 No Content

Verify 2FA Code​

POST /v1/auth/2fa/verify

Used during login when 2FA is enabled.

Request Body:

{
  "code": "123456",
  "session_token": "temporary-session-token"
}

Response:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": "2024-01-16T10:30:00Z"
  }
}

Change Password​

POST /v1/auth/change-password

Request Body:

{
  "current_password": "old-password",
  "new_password": "new-secure-password"
}

Response:

{
  "data": {
    "message": "Password changed successfully"
  }
}

Sessions​

List Active Sessions​

GET /v1/auth/sessions

Response:

{
  "data": [
    {
      "id": "sess_abc123",
      "device": "Chrome on macOS",
      "ip_address": "192.168.1.1",
      "location": "San Francisco, CA",
      "current": true,
      "last_active": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-15T08:00:00Z"
    },
    {
      "id": "sess_def456",
      "device": "CLI",
      "ip_address": "10.0.0.1",
      "location": "New York, NY",
      "current": false,
      "last_active": "2024-01-14T18:00:00Z",
      "created_at": "2024-01-14T09:00:00Z"
    }
  ]
}

Revoke Session​

DELETE /v1/auth/sessions/:id

Response: 204 No Content

Revoke All Sessions​

DELETE /v1/auth/sessions

Revokes all sessions except the current one.

Response: 204 No Content

Error Responses​

401 Unauthorized​

{
  "error": "invalid_credentials",
  "message": "Invalid email or password"
}

403 Forbidden​

{
  "error": "2fa_required",
  "message": "Two-factor authentication required",
  "session_token": "temporary-session-token"
}

429 Too Many Requests​

{
  "error": "rate_limited",
  "message": "Too many login attempts. Please try again in 15 minutes.",
  "retry_after": 900
}