# Authorization

## Overview

The WebWork Tracker REST API V2 supports two authentication methods: **OAuth2** and **Personal Access Tokens**. Both methods use Bearer token authentication in the HTTP Authorization header.

Choose the authentication method that best fits your use case:

- **OAuth2** - Best for applications that need user authorization and automatic token refresh
- **Personal Access Tokens** - Best for scripts, testing, or simple integrations


## OAuth2 Authentication

OAuth2 authentication uses the Authorization Code flow, which is ideal for applications that need to access user data on their behalf. This method provides secure, user-authorized access with automatic token refresh capabilities.

### Getting Started with OAuth2

#### Step 1: Create an OAuth2 Application

Before you can use OAuth2 authentication, you need to register your application:

1. Log in to your WebWork account
2. Navigate to **Settings > REST API > OAuth2 Apps**
3. Click **"Create App"**
4. Enter your application name (e.g., "My Integration App")
5. Provide your redirect URI (where users will be redirected after authorization)
  - Example: `https://myapp.com/callback`
  - Must match exactly when making authorization requests
6. Select the grant type:
  - **Authorization Code Grant** - For web applications with user authorization
  - **Client Credentials Grant** - For server-to-server authentication
7. Click **"Create"**
8. **Important:** Copy your **Client ID** and **Client Secret** immediately - you won't be able to see the secret again!


**Create OAuth2 App:** [https://webwork-tracker.com/app/settings/rest-api](https://webwork-tracker.com/app/settings/rest-api)

#### Step 2: Authorization Flow

The OAuth2 Authorization Code flow consists of three main steps:

**Step 1: Redirect User to Authorization URL**

Redirect the user to the authorization URL with your client credentials:


```
GET https://webwork-tracker.com/oauth/authorize?
    client_id=YOUR_CLIENT_ID&
    redirect_uri=YOUR_REDIRECT_URI&
    response_type=code&
    scope=read write
```

**Parameters:**

- `client_id` - Your OAuth2 application's Client ID
- `redirect_uri` - Must match the redirect URI registered with your app
- `response_type` - Always `code` for Authorization Code flow
- `scope` - Space-separated list of requested scopes (`read`, `write`, `admin`)


**Step 2: User Authorizes Your Application**

The user will be redirected to WebWork's authorization page. After they approve your application, they'll be redirected back to your `redirect_uri` with an authorization code:


```
https://your-redirect-uri.com/callback?code=AUTHORIZATION_CODE
```

**Step 3: Exchange Authorization Code for Tokens**

Exchange the authorization code for an access token and refresh token:


```bash
POST https://api.webwork-tracker.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
code=AUTHORIZATION_CODE&
redirect_uri=YOUR_REDIRECT_URI
```

**Response:**


```json
{
  "token_type": "Bearer",
  "expires_in": 1296000,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh_token": "def50200a1b2c3d4e5f6..."
}
```

#### Step 3: Using Access Tokens

Include the access token in all API requests using the Authorization header:


```bash
GET https://api.webwork-tracker.com/api/v2/workspaces
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
```

#### Step 4: Refreshing Access Tokens

Access tokens expire after **15 days**. Use the refresh token to obtain a new access token before expiration:


```bash
POST https://api.webwork-tracker.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
refresh_token=YOUR_REFRESH_TOKEN
```

**Response:**


```json
{
  "token_type": "Bearer",
  "expires_in": 1296000,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh_token": "def50200a1b2c3d4e5f6..." // New refresh token
}
```

**Important:** Always save the new refresh token - the old one becomes invalid after use.

### OAuth2 Token Expiration

- **Access tokens:** Expire after **15 days**
- **Refresh tokens:** Expire after **30 days**
- Always refresh your access token before it expires to maintain uninterrupted API access


### OAuth2 Scopes

Scopes define what permissions your application has. When creating an OAuth2 application or Personal Access Token, you can specify which scopes the token should have:

- **`read`** - Read access to resources (projects, tasks, reports, members, workspaces)
  - Allows GET requests to retrieve data
  - Required for viewing workspace information, members, projects, tasks, etc.
- **`write`** - Write access to create and update resources
  - Allows POST and PUT requests to create and modify data
  - Required for creating projects, tasks, members, updating resources, etc.
- **`admin`** - Administrative access to all resources
  - Full access including DELETE operations
  - Required for deleting resources, managing workspace settings, etc.


**How Scopes Work:**

- When creating a Personal Access Token, you can specify scopes in the `scopes` array
- When using OAuth2 Authorization Code flow, request scopes in the authorization URL: `scope=read write`
- Users can approve or deny specific scopes during authorization
- Tokens store their granted scopes, which can be checked programmatically


**Example: Requesting Scopes in OAuth2 Flow**


```
GET https://webwork-tracker.com/oauth/authorize?
    client_id=YOUR_CLIENT_ID&
    redirect_uri=https://your-app.com/callback&
    response_type=code&
    scope=read write
```

### OAuth2 Endpoints

- **Authorization URL:** `https://webwork-tracker.com/oauth/authorize`
- **Token URL:** `https://api.webwork-tracker.com/oauth/token`


The token URL is used for both obtaining new tokens and refreshing expired tokens.

### OAuth2 Configuration Values

When configuring OAuth2 in your application or API client (like Postman), use these values:

- **Auth URL:** `https://webwork-tracker.com/oauth/authorize`
- **Access Token URL:** `https://api.webwork-tracker.com/oauth/token`
- **Client ID:** Your OAuth2 App Client ID (from Settings > REST API)
- **Client Secret:** Your OAuth2 App Client Secret (from Settings > REST API)
- **Scope:** `read write` (or `admin`)
- **State:** (optional - leave empty or use random string)
- **Client Authentication:** `Send as Basic Auth header`
- **Redirect URI:** Must match exactly the redirect URI you registered when creating the OAuth2 app (e.g., `https://your-app.com/callback`)


## Personal Access Tokens

Personal Access Tokens provide a simpler authentication method, perfect for:

- Scripts and automation
- Testing and development
- Applications that don't need user authorization flows
- Long-running integrations


### Getting Started with Personal Access Tokens

#### Step 1: Create a Personal Access Token

1. Log in to your WebWork account
2. Navigate to **Settings > REST API > Personal Access Tokens**
3. Click **"Create Token"**
4. Enter a descriptive name (e.g., "My Integration", "Production API", "Testing Script")
5. Click **"Create Token"**
6. **Important:** Copy the token immediately - you won't be able to see it again!


**Create Personal Access Token:** [https://webwork-tracker.com/app/settings/rest-api](https://webwork-tracker.com/app/settings/rest-api)

#### Step 2: Using Personal Access Tokens

Include the token in all API requests using the Authorization header:


```bash
GET https://api.webwork-tracker.com/api/v2/workspaces
Authorization: Bearer your-personal-access-token-here
```

### Personal Access Token Management

- **View Tokens:** See all your active tokens in **Settings > REST API**
- **Token Expiration:** Tokens expire after **6 months**
- **Revoke Tokens:** Archive (revoke) tokens anytime if they're compromised
- **No Refresh:** Personal Access Tokens don't support refresh - create a new token when one expires


### Personal Access Token vs OAuth2

| Feature | Personal Access Tokens | OAuth2 |
|  --- | --- | --- |
| **Setup Complexity** | Simple (one step) | More complex (app registration + flow) |
| **User Authorization** | Not required | Required |
| **Token Expiration** | 6 months | 15 days (access), 30 days (refresh) |
| **Token Refresh** | No (create new token) | Yes (automatic refresh) |
| **Best For** | Scripts, testing, simple integrations | Production applications, user-facing apps |


## Access Requirements

**Important:** REST API V2 access is restricted to:

- **Workspace Owners**
- **Executive Managers**


Only users with these roles can:

- Create OAuth2 applications
- Generate Personal Access Tokens
- Make API requests


If you don't have the required role, contact your workspace owner or administrator to request access.

## Security Best Practices

1. **Never commit tokens to version control** - Use environment variables or secure secret management
2. **Rotate tokens regularly** - Create new tokens periodically and revoke old ones
3. **Use HTTPS only** - Always use HTTPS in production
4. **Store tokens securely** - Use secure storage mechanisms appropriate for your platform
5. **Monitor token usage** - Regularly review active tokens and revoke unused or compromised ones
6. **Use appropriate scopes** - Request only the minimum scopes needed for your application


## Troubleshooting

### "Unauthorized" Error (401)

- Check that your token is correctly included in the Authorization header
- Verify the token hasn't expired
- Ensure you're using the correct token format: `Authorization: Bearer <token>`


### "Forbidden" Error (403)

- Verify you have the required role (Owner or Executive Manager)
- Check that you're using the correct workspace_id for workspace-specific endpoints


### Token Expired

- **OAuth2:** Use the refresh token to obtain a new access token
- **Personal Access Token:** Create a new token in Settings > REST API


### Invalid Redirect URI

- Ensure the redirect URI in your authorization request exactly matches the one registered with your OAuth2 app
- Check for trailing slashes, HTTP vs HTTPS, and exact path matching


## Verifying Authentication

### Check if Your Token is Valid

Test your authentication with a simple API call:


```bash
# Test with OAuth2 or Personal Access Token
curl -X GET "https://api.webwork-tracker.com/api/v2/workspaces" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Success Response (200):**


```json
{
  "success": true,
  "data": [...],
  "meta": {...}
}
```

**Authentication Error (401):**


```json
{
  "success": false,
  "message": "Unauthorized. Please provide a valid Bearer token or Basic Auth credentials."
}
```

## Need Help?

- **API Support:** [api-support@webwork-tracker.com](mailto:api-support@webwork-tracker.com)
- **Settings Page:** [https://webwork-tracker.com/app/settings/rest-api](https://webwork-tracker.com/app/settings/rest-api)