Authentication

The ZenFlip API supports three authentication methods: email/password login (JWT tokens), Google OAuth, and API keys. All protected endpoints require a valid Bearer token in the Authorization header.

Email and Password Login

Sign Up

Create a new account and organization:

After signup, a verification email is sent. The account must be verified before full access is granted.

Login

Exchange credentials for JWT tokens:

Response:

The accessToken expires after the number of seconds indicated by expiresIn (default: 3600 seconds / 1 hour). The refreshToken has a longer lifetime and is used to obtain new access tokens without re-entering credentials.

Using Tokens

Include the access token in the Authorization header for all protected requests:

Using JavaScript fetch:

Token Refresh

When the access token expires, use the refresh token to obtain a new pair without prompting the user to log in again:

Response:

Both the access token and refresh token are rotated on each refresh call. Store the new refresh token and discard the old one. If you use the ZenFlip web dashboard, tokens are also set as httpOnly cookies automatically.

JavaScript Refresh Example

Google OAuth

ZenFlip supports Google OAuth for single sign-on. This flow is browser-based and uses server-side redirects.

Flow

1. Redirect the user to https://api.zenflip.io/v1/auth/google.

2. The user authenticates with Google and grants consent.

3. Google redirects to https://api.zenflip.io/v1/auth/google/callback.

4. The API sets httpOnly authentication cookies and redirects the user to your frontend callback URL (e.g., https://app.zenflip.io/auth/google/callback?isNew=0).

The isNew parameter indicates whether a new account was created (1) or the user logged into an existing account (0). Your frontend reads this flag to decide whether to show onboarding.

Integration Example

After the OAuth callback, the user's browser has authentication cookies set. Subsequent API calls from the browser will be authenticated via those cookies.

API Keys (Server-to-Server)

For backend integrations, webhooks, or CI/CD pipelines, API keys provide a simpler authentication path that does not require the login/refresh flow.

Generating an API Key

1. Go to Settings > API Keys in the ZenFlip dashboard.

2. Click Generate New Key.

3. Copy and store the key securely. It is shown only once.

Using an API Key

Pass the API key as a Bearer token:

API keys inherit the full permissions of the organization they belong to. Treat them with the same care as passwords --- never expose them in client-side code, version control, or logs.

Email Verification

New accounts require email verification. The API provides endpoints for verifying and resending the verification email:

Password Reset

If a user forgets their password, initiate a reset flow:

Current User Profile

Retrieve the authenticated user's profile:

Logout

Invalidate the current session and clear cookies:

Rate Limits

Authentication endpoints have their own rate limits to prevent abuse: