Authentication¶

Ospobox uses JWT (JSON Web Tokens) for API authentication.

Overview¶

The authentication flow:

1. Login with email and password to get access and refresh tokens
2. Use access token in the Authorization header for API requests
3. Refresh tokens before they expire using the refresh token

sequenceDiagram
    participant Client
    participant API
    participant Database

    Client->>API: POST /api/auth/login
    API->>Database: Verify credentials
    Database-->>API: User data
    API-->>Client: Access + Refresh tokens

    Client->>API: GET /api/organizations
    Note over Client,API: Authorization: Bearer <access_token>
    API-->>Client: Organizations data

    Note over Client: Token expiring...
    Client->>API: POST /api/auth/refresh
    API-->>Client: New access token

Login¶

Obtain tokens by logging in with email and password:

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "your-password"}'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer"
}

Using Access Tokens¶

Include the access token in the Authorization header:

curl http://localhost:8000/api/organizations/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token Expiration¶

Access tokens are short-lived for security. When they expire, use the refresh token to obtain a new one.

Refreshing Tokens¶

Before the access token expires, use the refresh token to get a new one:

curl -X POST http://localhost:8000/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer"
}

Registration¶

Create a new account:

curl -X POST http://localhost:8000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "password": "secure-password",
    "name": "New User",
    "account_name": "My Company"
  }'

Response includes tokens for immediate use:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer"
}

Error Responses¶

Invalid Credentials¶

{
  "detail": "Invalid email or password"
}

Status: 401 Unauthorized

Expired Token¶

{
  "detail": "Token has expired"
}

Status: 401 Unauthorized

Missing Token¶

{
  "detail": "Missing authorization header"
}

Status: 401 Unauthorized

Token Structure¶

Access tokens contain:

OAuth Integration¶

For platform connections (GitHub, GitLab), Ospobox uses OAuth 2.0:

Starting OAuth Flow¶

curl http://localhost:8000/api/oauth/github/start

Response:

{
  "authorize_url": "https://github.com/login/oauth/authorize?...",
  "state": "random-state-value"
}

Redirect the user to authorize_url. After authorization, they'll be redirected back to your callback URL with an authorization code.

OAuth Callback¶

The callback is handled automatically by Ospobox. After successful authorization, the platform connection is stored and can be used for syncing.

Best Practices¶

1. Store tokens securely - Use secure storage (httpOnly cookies, secure local storage)
2. Refresh proactively: refresh tokens before they expire
3. Handle expiration - Implement token refresh in your client
4. Use HTTPS - Always use HTTPS in production to protect tokens in transit