Rotate the API key

GET /api/ApiClient/refreshApiKey

Authentication

Send your private API key in the X-Api-Key header. Keep it on your server.

Changes state: this GET performs an action. Do not automatically retry it after an uncertain response; verify the resulting state first.

Returns ApiClientWithApiKey, containing apiClient and apiKey. Update all integrations after rotation. Old keys may remain accepted while cached; see Key rotation.

Request example

Examples use illustrative values. Set FERRETLY_API_KEY in your server environment for JavaScript, Python, and C#. Replace sample IDs, URLs, and profile values before use.

curl

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

JavaScript

const response = await fetch("https://api.ferretly.com/api/ApiClient/refreshApiKey", {
  "method": "GET",
  "headers": {
    "X-Api-Key": process.env.FERRETLY_API_KEY,
    "Accept": "application/json"
  }
});
if (!response.ok) throw new Error("HTTP " + response.status);
console.log(await response.json());

Python

import os
import requests

response = requests.request(
    "GET",
    "https://api.ferretly.com/api/ApiClient/refreshApiKey",
    headers={"X-Api-Key":os.environ["FERRETLY_API_KEY"],"Accept":"application/json"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

C#

using System;
using System.IO;
using System.Net.Http;
using System.Text;

using var http = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api.ferretly.com/api/ApiClient/refreshApiKey");
request.Headers.Add("X-Api-Key", Environment.GetEnvironmentVariable("FERRETLY_API_KEY"));
request.Headers.Accept.ParseAdd("application/json");
using var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Responses

200

Success

• text/plain: ApiClientWithApiKey
• application/json: ApiClientWithApiKey
• text/json: ApiClientWithApiKey

Response example

Illustrative, shortened HTTP 200 response. Optional fields can be absent or null.

{
  "apiClient": {
    "subscriberId": "11111111-1111-4111-8111-111111111111",
    "organizationId": "22222222-2222-4222-8222-222222222222",
    "owner": "integrations@example.com",
    "statusUpdateCallbackUrl": "https://example.com/hooks/ferretly",
    "technicalContactEmail": "integrations@example.com",
    "allowPreferenceProfileUpdate": false
  },
  "apiKey": "YOUR_NEW_API_KEY"
}

Response properties

Property	Type	Description
apiClient	ApiClient
apiKey	string	The API Key for this client Nullable.

apiClient properties

Property	Type	Description
subscriberId	string (uuid)	The id of the Ferretly user associated with the API client key
organizationId	string (uuid)	The id of the Ferretly organization associated with the API client key
owner	string	Name of the API client key owner Nullable.
permissions	string	Comma-separated list of permissions associated with the API client Nullable.
statusUpdateCallbackUrl	string	Webhook URL Nullable.
clientSpecificProperties	string	A place to store additional, generic properties about the API Client Nullable.
technicalContactEmail	string	Email address of the technical contact for this API client organization. Nullable.
allowPreferenceProfileUpdate	boolean	Gets or sets a value indicating whether this API client is allowed to update preference profiles.

Related guides

• Authentication
• With Analyst Assistance
• Without Analyst Assistance
• Errors and status codes