---
title: "Authentication Overview"
description: "Learn how to authenticate with the TraceRTM API using API keys, OAuth 2.0, or JWT tokens"
keywords: [authentication, api keys, oauth, jwt, security]
---

# Authentication Overview

All TraceRTM API requests require authentication to ensure secure access to your data. TraceRTM supports multiple authentication methods to fit different use cases.

## Authentication Methods

TraceRTM provides three main authentication methods:

### 1. API Keys
**Best for**: Server-to-server communication, automated scripts, CI/CD pipelines

- Simple, permanent keys
- No token expiration
- Easy to rotate
- Scoped permissions

👉 [API Keys Guide](./02-api-keys)

### 2. OAuth 2.0
**Best for**: User-facing applications, third-party integrations

- Standard OAuth 2.0 flow
- User consent and authorization
- Refresh token support
- Granular scopes

👉 [OAuth 2.0 Guide](./03-oauth2)

### 3. JWT Tokens
**Best for**: Stateless authentication, microservices, distributed systems

- JSON Web Tokens
- Self-contained claims
- Short-lived access tokens
- Refresh token support

👉 [JWT Tokens Guide](./04-jwt)

## Quick Start

### Using API Keys (Recommended for Automation)

```bash
# Set your API key
export TRACERTM_API_KEY="rtm_live_abc123..."

# Make a request
curl -X GET "https://api.tracertm.dev/v1/projects" \
  -H "X-API-Key: $TRACERTM_API_KEY" \
  -H "Content-Type: application/json"
```

### Using Bearer Tokens (OAuth/JWT)

```bash
# Set your access token
export TRACERTM_TOKEN="eyJhbGciOiJSUzI1NiIs..."

# Make a request
curl -X GET "https://api.tracertm.dev/v1/projects" \
  -H "Authorization: Bearer $TRACERTM_TOKEN" \
  -H "Content-Type: application/json"
```

## Authentication Headers

### API Key Authentication
```http
X-API-Key: rtm_live_abc123...
```

### Bearer Token Authentication
```http
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
```

## Public Access

When authentication is disabled in your TraceRTM instance, requests without authentication headers will be treated as public access with read-only permissions.

```bash
# Public access (if auth disabled)
curl -X GET "https://api.tracertm.dev/v1/projects"
```

## Authentication Flow

```mermaid
graph TD
    A[Client Application] -->|1. Request Access| B{Authentication Method?}
    B -->|API Key| C[API Key Validation]
    B -->|OAuth 2.0| D[OAuth Flow]
    B -->|JWT| E[JWT Validation]
    C -->|Valid| F[Access Granted]
    D -->|Authorized| G[Access Token]
    E -->|Valid| F
    G --> F
    F --> H[API Request]
```

## Security Best Practices

1. **Never commit credentials**: Store API keys and tokens in environment variables or secure vaults
2. **Use HTTPS**: Always use HTTPS in production
3. **Rotate keys regularly**: Update API keys periodically
4. **Use least privilege**: Grant only necessary permissions
5. **Monitor usage**: Review API access logs regularly

👉 [Security Best Practices](./07-best-practices)

## Error Responses

### Invalid API Key
```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key"
  }
}
```

### Missing Authentication
```json
{
  "error": {
    "code": "authentication_required",
    "message": "Authorization required"
  }
}
```

### Expired Token
```json
{
  "error": {
    "code": "token_expired",
    "message": "Token has expired",
    "refresh_url": "/api/auth/refresh"
  }
}
```

## Rate Limiting

All authenticated requests are subject to rate limiting based on your plan:

| Plan | Requests/minute |
|------|----------------|
| Free | 60 |
| Pro | 300 |
| Enterprise | 1,000 |

Rate limit information is included in response headers.

👉 [Rate Limiting Details](./06-rate-limiting)

## Scopes and Permissions

Different authentication methods support different permission scopes:

- **API Keys**: Project-level or global scopes
- **OAuth 2.0**: Granular user consent scopes
- **JWT Tokens**: Claims-based permissions

👉 [Scopes Guide](./05-scopes)

## Next Steps

1. **Choose your method**: Select the authentication method that fits your use case
2. **Get credentials**: Generate API keys or set up OAuth
3. **Make your first request**: Test authentication with a simple API call
4. **Review best practices**: Ensure secure implementation

## Related Documentation

- [API Keys](./02-api-keys) - Detailed API key guide
- [OAuth 2.0](./03-oauth2) - OAuth implementation
- [JWT Tokens](./04-jwt) - JWT authentication
- [Scopes](./05-scopes) - Permission scopes
- [Rate Limiting](./06-rate-limiting) - Rate limit details
- [Best Practices](./07-best-practices) - Security guidelines
