Start OAuth Flow

Initiate OAuth authentication with a provider.

POST /v1/auth/login

Request

{
  "provider": "google",
  "redirectUri": "https://yourapp.com/auth/callback",
  "scopes": ["email", "profile"],
  "state": "optional-state-value"
}

Response

{
  "data": {
    "authUrl": "https://accounts.google.com/o/oauth2/v2/auth?...",
    "state": "state-value"
  }
}

---

Handle OAuth Callback

Exchange OAuth code for tokens.

POST /v1/auth/callback

Request

{
  "provider": "google",
  "code": "oauth-code-from-provider",
  "state": "state-value"
}

Response

{
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "name": "John Doe"
    },
    "accessToken": "eyJ...",
    "refreshToken": "eyJ...",
    "expiresAt": "2024-01-01T00:15:00Z"
  }
}

---

Send Magic Link

Send a passwordless login link via email.

POST /v1/auth/magic-link

Request

{
  "email": "user@example.com",
  "redirectUri": "https://yourapp.com/auth/verify"
}

Response

{
  "data": {
    "sent": true,
    "expiresAt": "2024-01-01T00:10:00Z"
  }
}

---

Verify Magic Link

Verify a magic link token.

POST /v1/auth/verify

Request

{
  "token": "magic-link-token"
}

Response

{
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com"
    },
    "accessToken": "eyJ...",
    "refreshToken": "eyJ...",
    "expiresAt": "2024-01-01T00:15:00Z"
  }
}

---

Refresh Token

Get a new access token using a refresh token.

POST /v1/auth/refresh

Request

{
  "refreshToken": "eyJ..."
}

Response

{
  "data": {
    "accessToken": "eyJ...",
    "refreshToken": "eyJ...",
    "expiresAt": "2024-01-01T00:15:00Z"
  }
}

---

Logout

Revoke the current session.

POST /v1/auth/logout

Headers

Authorization: Bearer ACCESS_TOKEN

Response

{
  "data": {
    "success": true
  }
}

Error Codes

Code	Description
INVALID_PROVIDER	Unknown OAuth provider
INVALID_CODE	OAuth code invalid or expired
INVALID_STATE	State mismatch (CSRF)
MAGIC_LINK_EXPIRED	Magic link has expired
MAGIC_LINK_USED	Magic link already used
REFRESH_TOKEN_EXPIRED	Refresh token has expired
REFRESH_TOKEN_REVOKED	Session was revoked