API

Authentication

How to authenticate API requests using API keys or OAuth tokens.

API Keys

The simplest way to authenticate is with an API key. Include your key in the Authorization header of every request:

curl -H "Authorization: Bearer frd_live_abc123..." \
  https://api.joinfriender.com/v1/assessments

API keys are scoped to your organization and can be created from the Friender dashboard under Settings → API Keys. You can create multiple keys with different permission scopes.

Key Types

Prefix	Environment	Description
`frd_live_`	Production	Full access to your organization's assessment data
`frd_test_`	Sandbox	Access to sandbox data only — safe for development and testing

Permission Scopes

Scope	Description
`assessments:read`	Read assessment status and reports
`assessments:write`	Create and modify assessments
`integrations:read`	View connected integrations and their status
`integrations:write`	Connect and disconnect integrations
`webhooks:manage`	Create, update, and delete webhook endpoints

OAuth 2.0

For applications that act on behalf of individual users, we support OAuth 2.0 Authorization Code flow. This is recommended when building integrations that need user-specific context.

Authorization URL

https://auth.joinfriender.com/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://your-app.com/callback&
  response_type=code&
  scope=assessments:read integrations:read

Token Exchange

POST https://auth.joinfriender.com/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "auth_code_from_callback",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "redirect_uri": "https://your-app.com/callback"
}

Token Response

{
  "access_token": "frd_oauth_abc123...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "frd_refresh_xyz789...",
  "scope": "assessments:read integrations:read"
}

Security Best Practices

Never expose API keys in client-side code or public repositories
Use environment variables to store keys in your application
Rotate keys regularly — we recommend every 90 days
Use the minimum required scopes for each key
Revoke compromised keys immediately from the dashboard
Use test keys (frd_test_) during development