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:

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:

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:

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:

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:

{
  "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

{
  "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

{
  "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