Authentication

Send the API key header

Send your private API key in X-Api-Key when calling the documented Ferretly endpoints:

X-Api-Key: YOUR_API_KEY

The OpenAPI security scheme is named ApiKey. Request access through Ferretly Integrations.

Keep the key in your integration backend. Do not embed it in publicly delivered browser or mobile code, source control, URLs, screenshots, or documentation feedback.

Verify your key

curl --fail -sS https://api.ferretly.com/api/ApiClient \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

A successful response uses the ApiClient schema:

Field	Meaning
organizationId	Associated organization
subscriberId	Associated Ferretly user
owner	API-client owner name
permissions	Comma-separated permission list
statusUpdateCallbackUrl	Registered callback URL
technicalContactEmail	Technical contact
allowPreferenceProfileUpdate	Create/update permission flag for preference profiles
clientSpecificProperties	Optional client-specific string

Do not expect this operation to return the API key itself.

Authentication errors

Missing or invalid API keys return 401. A request without a key to GET /api/ApiClient returns an application/problem+json body. Permission failures can return 403.

See Errors and status codes for an example response and endpoint-specific handling.

Manage the API client

Method	Endpoint	Input
GET	/api/ApiClient	No body
GET	/api/ApiClient/getOrganization	No body
POST	/api/ApiClient/updateWebHook	JSON string containing the callback URL
POST	/api/ApiClient/updateTechnicalContact	JSON string containing the contact email
POST	/api/ApiClient/updateClientSpecificProperties	JSON string containing the properties value
GET	/api/ApiClient/refreshApiKey	No body; changes the key

Use a raw JSON string for these string-valued write bodies, rather than an object wrapper. Consult the API reference for exact responses and media types.

Key rotation

GET /api/ApiClient/refreshApiKey changes credentials and returns ApiClientWithApiKey, containing apiClient and apiKey.

Coordinate rotation with all users of the key. Do not invoke the endpoint from a link, browser preview, or automatic retry loop.

Old keys may remain accepted while key lookups are cached. Update all integrations promptly after rotation. If you need to revoke a compromised key, contact Ferretly Integrations; rotation does not provide a fixed overlap window or guarantee immediate revocation.

JSON and binary responses

Send Content-Type: application/json for JSON request bodies. Each endpoint reference lists its supported request and response media types.

Report downloads return binary content. See Results and reports.