- API Keys - For programmatic access
- Access Tokens - For user authentication
API keys
API keys are used for programmatic access to the FirstQuadrant API. They are prefixed withfqa_
and can be generated from the web application’s settings.
Obtaining an API key
- Log in to your FirstQuadrant account
- Go to Settings > API Keys
- Click “Create API Key”
- Give your API key a name and select the required scopes
- Copy the generated API key immediately - you won’t be able to see it again
Using API keys
Include your API key in theAuthorization
header:
API key scopes
API keys can be restricted to specific scopes using the following format:<resource>
is the resource type (e.g.,user
,organization
,campaign
)<action>
is the action type (e.g.,*
for all actions)<permission>
is eitherread
orwrite
urn:firstquadrant:user:*:read
- Read access to user resourcesurn:firstquadrant:organization:*:write
- Write access to organization resourcesurn:firstquadrant:*:*:read
- Read access to all resources (sudo)
Organization context
When using API keys, you must include the organization ID in theFirstQuadrant-Organization-ID
header:
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
- Log in to your FirstQuadrant account through the web application
- Your access token will be automatically included in all API requests made through the web interface
- For programmatic access, you can use the refresh token flow described below
Using access tokens
Include your access token in theAuthorization
header:
Refresh token flow
- When you first authenticate, you’ll receive both an access token and a refresh token
- Access tokens expire after 24 hours
- To get a new access token, send a POST request to
/auth
with your refresh token:
Error responses
The API will return the following error responses for authentication issues:401 Unauthorized
403 Forbidden
Security best practices
- Never share your API keys or access tokens
- Rotate API keys regularly
- Use the minimum required scopes for API keys
- Store tokens securely and never commit them to version control
- Use environment variables for storing sensitive credentials