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

# Authentication

> How to authenticate your requests to the FirstQuadrant API

The FirstQuadrant API supports two types of authentication:

1. **API Keys** - For programmatic access
2. **Access Tokens** - For user authentication

## API keys

API keys are used for programmatic access to the FirstQuadrant API. They are prefixed with `fqa_` and can be generated from the web application's settings.

### Obtaining an API key

1. Log in to your FirstQuadrant account
2. Go to Settings > API Keys
3. Click "Create API Key"
4. Give your API key a name and select the required scopes
5. Copy the generated API key immediately - you won't be able to see it again

### Using API keys

Include your API key in the `Authorization` header:

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

### API key scopes

API keys can be restricted to specific scopes using the following format:

```
urn:firstquadrant:<resource>:<action>:<permission>
```

Where:

* `<resource>` is the resource type (e.g., `user`, `organization`, `campaign`)
* `<action>` is the action type (e.g., `*` for all actions)
* `<permission>` is either `read` or `write`

Examples:

* `urn:firstquadrant:user:*:read` - Read access to user resources
* `urn:firstquadrant:organization:*:write` - Write access to organization resources
* `urn:firstquadrant:*:*:read` - Read access to all resources (sudo)

### Organization context

When using API keys, you must include the organization ID in the `FirstQuadrant-Organization-ID` header:

```bash theme={null}
FirstQuadrant-Organization-ID: org_123
```

## Access tokens

Access tokens are used to authenticate users who are logged into the FirstQuadrant web application. They are JWT tokens that contain user information and permissions.

### Obtaining an access token

1. Log in to your FirstQuadrant account through the web application
2. Your access token will be automatically included in all API requests made through the web interface
3. For programmatic access, you can use the refresh token flow described below

### Using access tokens

Include your access token in the `Authorization` header:

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

### Refresh token flow

1. When you first authenticate, you'll receive both an access token and a refresh token
2. Access tokens expire after 24 hours
3. To get a new access token, send a POST request to `/auth` with your refresh token:

```bash theme={null}
curl -X POST https://api.firstquadrant.ai/auth \
  -H "Content-Type: application/json" \
  -d '{"token": "your_refresh_token"}'
```

The response will include new access and refresh tokens:

```json theme={null}
{
  "userId": "user_123",
  "sessionId": "session_456",
  "accessToken": "new_access_token",
  "refreshToken": "new_refresh_token"
}
```

## Error responses

The API will return the following error responses for authentication issues:

### 401 Unauthorized

```json theme={null}
{
  "code": "missing_authorization",
  "status": 401,
  "message": "You are not logged in",
  "description": "This resource is only available when you are logged in. Please use an access token or API key for authorization."
}
```

### 403 Forbidden

```json theme={null}
{
  "code": "missing_scopes",
  "status": 403,
  "message": "Missing scopes",
  "description": "This resource is not available to you. Please ensure your access token or API key has the required scopes."
}
```

## Security best practices

1. Never share your API keys or access tokens
2. Rotate API keys regularly
3. Use the minimum required scopes for API keys
4. Store tokens securely and never commit them to version control
5. Use environment variables for storing sensitive credentials