> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fentufsm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticating with the Fentu FSM API

## Overview

The Fentu FSM API uses token-based authentication. All API requests must include a valid authentication token in the request header.

<Note>
  Keep your API credentials secure. Never expose tokens in client-side code or public repositories.
</Note>

## Authentication Methods

### API Key Authentication

For server-to-server integrations:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

### OAuth 2.0

For user-authorized applications:

1. Redirect user to authorization endpoint
2. User grants permission
3. Receive authorization code
4. Exchange code for access token
5. Use access token for API requests

***

## Obtaining Credentials

### API Keys

<Steps>
  <Step title="Navigate to Settings">
    Go to Administration > Integrations > API
  </Step>

  <Step title="Create API Key">
    Click "Create API Key"
  </Step>

  <Step title="Set Permissions">
    Configure what the key can access
  </Step>

  <Step title="Copy Key">
    Save the generated key securely
  </Step>
</Steps>

<Warning>
  API keys are shown only once when created. Store them securely immediately. If lost, you must create a new key.
</Warning>

### OAuth Credentials

For OAuth applications:

1. Register your application
2. Receive client ID and secret
3. Configure redirect URIs
4. Implement OAuth flow

***

## Making Authenticated Requests

### Request Headers

Include the authentication header in all requests:

```bash theme={null}
curl -X GET "https://api.fentu.io/v1/work-orders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### Example Request

```javascript theme={null}
const response = await fetch('https://api.fentu.io/v1/work-orders', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
```

***

## Token Management

### Token Expiration

| Token Type        | Lifetime                      |
| ----------------- | ----------------------------- |
| **API Key**       | No expiration (until revoked) |
| **Access Token**  | 1 hour                        |
| **Refresh Token** | 30 days                       |

### Refreshing Tokens

For OAuth access tokens:

```bash theme={null}
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

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

### Revoking Tokens

To invalidate a token:

```bash theme={null}
POST /oauth/revoke
Authorization: Bearer YOUR_TOKEN
```

***

## Permissions & Scopes

### Available Scopes

| Scope               | Access                     |
| ------------------- | -------------------------- |
| `read:work-orders`  | View work orders           |
| `write:work-orders` | Create/update work orders  |
| `read:customers`    | View customers             |
| `write:customers`   | Create/update customers    |
| `read:assets`       | View assets                |
| `write:assets`      | Create/update assets       |
| `admin`             | Full administrative access |

### Requesting Scopes

Include scopes in authorization request:

```
https://api.fentu.io/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT&
  scope=read:work-orders write:work-orders&
  response_type=code
```

***

## Error Handling

### Authentication Errors

| Error Code | Meaning                  | Resolution                |
| ---------- | ------------------------ | ------------------------- |
| `401`      | Invalid or missing token | Check token and try again |
| `403`      | Insufficient permissions | Request needed scopes     |
| `429`      | Rate limited             | Wait and retry            |

### Error Response Format

```json theme={null}
{
  "error": "unauthorized",
  "error_description": "Invalid or expired token",
  "status": 401
}
```

***

## Rate Limiting

### Limits

| Tier             | Requests/Hour |
| ---------------- | ------------- |
| **Standard**     | 1,000         |
| **Professional** | 10,000        |
| **Enterprise**   | Unlimited     |

### Rate Limit Headers

Responses include rate limit information:

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
```

### Handling Rate Limits

When rate limited:

1. Check `X-RateLimit-Reset` header
2. Wait until reset time
3. Retry request
4. Consider caching responses

***

## Security Best Practices

<AccordionGroup>
  <Accordion title="Secure Storage" icon="lock">
    Store credentials in secure vaults or environment variables. Never hardcode in source code.
  </Accordion>

  <Accordion title="Use HTTPS" icon="shield">
    Always use HTTPS for API requests. Never send credentials over unencrypted connections.
  </Accordion>

  <Accordion title="Minimum Scopes" icon="sliders">
    Request only the scopes you need. Don't request admin access for read-only operations.
  </Accordion>

  <Accordion title="Rotate Keys" icon="sync">
    Periodically rotate API keys. Immediately revoke any compromised credentials.
  </Accordion>

  <Accordion title="Monitor Usage" icon="chart-line">
    Monitor API usage for unusual patterns. Investigate unexpected spikes.
  </Accordion>

  <Accordion title="IP Restrictions" icon="network-wired">
    Where possible, restrict API access to known IP addresses.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="API Introduction" icon="code" href="/api-reference/introduction">
    API overview
  </Card>

  <Card title="Work Orders API" icon="clipboard-list" href="/api-reference/endpoints/work-orders">
    Work order endpoints
  </Card>

  <Card title="Customers API" icon="users" href="/api-reference/endpoints/customers">
    Customer endpoints
  </Card>

  <Card title="Integrations" icon="plug" href="/administration/settings/integrations">
    Integration setup
  </Card>
</CardGroup>