Overview

‍

Authentication in TaskForge is built on industry-standard OAuth 2.0 and API key-based mechanisms, giving you flexible options depending on your integration needs. Every request to the TaskForge API must be authenticated — unauthenticated requests will return a <401 Unauthorized> response.

‍

This guide walks you through the two primary authentication methods, how to manage credentials, and best practices for keeping your account secure.

‍

‍

API key authentication

‍

API keys are the simplest way to authenticate requests to the TaskForge API. Each workspace generates a unique API key that you include in the request header.

To generate your API key:

‍

1. Navigate to Settings → API in your workspace dashboard.
2. Click Generate New Key and give it a descriptive label.
3. Copy and store the key immediately — it will only be shown once.
4. Include the key in all API requests using the Authorization header.

‍

‍

API keys can be scoped to specific permissions (read-only, write, admin) and can be revoked at any time from the Settings panel.

‍

‍

‍

OAuth 2.0 authentication

‍

For applications that act on behalf of users, TaskForge supports the OAuth 2.0 Authorization Code flow. This is the recommended approach for third-party integrations and multi-user applications.

‍

The flow works as follows:

‍

1. Redirect the user to the TaskForge authorization endpoint with your <client_id> and requested <scopes>.
2. The user grants permission and is redirected back to your <redirect_uri> with an authorization code.
3. Exchange the code for an access token using your <client_secret>.
4. Use the access token in subsequent API requests.

‍

‍

Access tokens expire after 1 hour. Use the refresh token to obtain a new access token without requiring the user to re-authenticate.

‍

‍

Token management

‍

TaskForge issues both short-lived access tokens and long-lived refresh tokens. You should store refresh tokens securely and never expose them in client-side code or version control systems.

To rotate a compromised token:

‍

1. Go to Settings → Security → Active Sessions.
2. Identify and revoke the compromised token.
3. Generate a new token or re-authenticate via OAuth.

‍

‍

Two-factor authentication

‍

Two-factor authentication (2FA) adds an additional layer of protection to your TaskForge account. Once enabled, you will be prompted to enter a one-time code from your authenticator app each time you sign in. To enable 2FA:

‍

1. Go to Settings → Security.
2. Click Enable Two-Factor Authentication.
3. Scan the QR code using an authenticator app such as Google Authenticator or Authy.
4. Enter the 6-digit code to confirm setup.
5. Save your backup codes in a secure location.

‍

‍

Common authentication errors

‍

If you encounter authentication errors, here are the most common causes and how to resolve them:

‍

• 401 Unauthorized — Your API key or token is missing, expired, or invalid. Regenerate your credentials and retry.
• 403 Forbidden — Your credentials are valid but you lack permission for the requested resource.
• 429 Too Many Requests — You have exceeded the rate limit. Implement exponential backoff and retry after the period.