API Authentication

JWT access tokens are the default API auth mechanism, with refresh flow support and optional OAuth login for user-facing sessions.

Login

POST /api/v1/auth/login
{
  "email": "user@example.com",
  "password": "..."
}

Response:
{
  "access_token": "eyJ...",
  "refresh_token": "...",
  "expires_in": 3600
}

Use Token

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  https://api.docka.dev/v1/servers

Recommended Client Pattern

1. Authenticate once and cache the short-lived access token in memory.
2. Store the refresh token in a more protected location than the access token.
3. Retry a failed request once after a token refresh, then send the user back through login if refresh also fails.

Response Handling

• 401 usually means the access token is missing, expired, or invalid.
• 403 means the user is authenticated but not allowed to access the requested organization or resource.
• 429 means the client should back off and retry later.

Refresh

POST /api/v1/auth/refresh
{
  "refresh_token": "..."
}

OAuth Providers

• GET /api/v1/auth/github
• GET /api/v1/auth/google
• GET /api/v1/auth/gitlab