Skip to main content

Deactivated Key

🔑 Handling a Deactivated API Key​

When a survey's DQC API key is deactivated (soft-deleted or revoked from the DQC dashboard), authentication still succeeds — the key is simply revoked. What happens next depends on which surface the request hits, and the two surfaces behave differently on purpose:

  • Toolbox endpoints keep returning 200 with a Deactivated-Key special response, so a survey already in the field keeps running smoothly instead of breaking the moment its key is revoked.
  • Ingestion endpoints hard-reject with 403, because a revoked key must never write data into the platform.
SurfaceEndpoint(s)StatusBehavior
ToolboxGET /tools/toolbox/{apiKey}, DQCToolBox.getIdentity(...), DQCToolBox.getIdentityRequestId(...), GET /tools/request/{requestId}200Serves the Deactivated-Key special response, echoing the real requestId and, where the call carries one, the real surveyId.
IngestionPOST /data, POST /data/decipher, POST /data/{company}403Rejects the request with the Deactivated-Key marker before any persistence — nothing is stored.

Toolbox endpoints → 200 special response​

On the toolbox surface the Quality Tools wrapper does not start returning 401 / 403 errors. The request is still authenticated and the toolbox returns a 200 special response, so a survey that is already in the field keeps running smoothly instead of breaking the moment its key is revoked.

  • This prevents live surveys from erroring out after a key is revoked.
  • Responses are clearly marked so they can be identified and excluded from analysis.
  • Ensures a clean shutdown of data collection without disrupting the respondent experience.

GET /tools/toolbox/{apiKey} serves a neutered stub wrapper for a deactivated key. The stub contains no real fingerprinting, crypto, or network code, but it still exports the same public interface as the real wrapper — DQCToolBox.getIdentity(...) and DQCToolBox.getIdentityRequestId(...), both async — so nothing in the embedded survey has to change. It also runs the platform-specific persistence (Decipher / Forsta Survey.setPersistent(...)) with the deactivated values. Because the survey still receives its persisted data, the respondent keeps advancing normally and does not trip a Submission too quick special response.

If the survey's key has been deactivated, the Quality Tools will:

  • Echo the real identifiers the request carried, rather than the marker string. Which identifiers those are depends on the endpoint — see Which identifiers are echoed.
  • Assign Deactivated-Key to the participantId, country, subdivision, and deviceFailures attributes.
  • Return a device score of 0 for all device numeric metrics.
  • Return false for the isDuplicate property.
  • Return No data for survey history metrics (e.g., manualISQRate) and lastSurveyTaken.
  • Return 0 for quality checks (e.g., brandFamiliarity).
  • Return NONE for the persona attribute. See Personas.

Which identifiers are echoed​

CallrequestIdsurveyId
DQCToolBox.getIdentity(surveyId), from the stub served by GET /tools/toolbox/{apiKey}RealReal when the survey supplies one, Deactivated-Key when it does not
DQCToolBox.getIdentityRequestId(requestId), calling GET /tools/request/{requestId}RealDeactivated-Key — the call carries no surveyId

In every case participantId stays the Deactivated-Key marker.

Response Example​

This is the DQCToolBox.getIdentity(surveyId) shape, where both identifiers are real. Calling DQCToolBox.getIdentityRequestId(requestId) (GET /tools/request/{requestId}) returns the same shape but with surveyId set to Deactivated-Key.

{
  "requestId": "1757416517972.rWZN1D",
  "participantId": "Deactivated-Key",
  "dataTrustScore": 0,
  "persona": "NONE",
  "deviceScore": 0,
  "country": "Deactivated-Key",
  "subdivision": "Deactivated-Key",
  "lastSurveyTaken": "No data",
  "isDuplicate": false,
  "surveyId": "example.com/survey/123",
  "averageDeviceScore": 0,
  "lowestDeviceScore": 0,
  "totalSurveys": 0,
  "deviceFailures": [
    "Deactivated-Key"
  ],
  "completionRate": "No data",
  "duplicationRate": "No data",
  "failureRate": "No data",
  "qualificationRate": "No data",
  "manualISQRate": "No data",
  "automatedISQRate": "No data",
  "osqRate": "No data",
  "brandFamiliarity": 0,
  "openEnd": 0,
  "speeding": 0,
  "honeyPot": 0,
  "straightlining": 0,
  "distinctSupplierCount": 0,
  "suppliers": []
}

Ingestion endpoints → 403 (rejected)​

A deactivated key must never write data into the DQC platform. Every ingestion endpoint — POST /data, POST /data/decipher, and POST /data/{company} for other integrations — returns 403 with the Deactivated-Key marker when the key has been deactivated.

The request is rejected before any persistence — nothing is stored and nothing enters the processing pipeline. A revoked key stops ingesting immediately.

An active key is unaffected and ingests normally, returning 200 with Integration data stored successfully.

When does this happen?​

A Deactivated-Key response is returned only when the survey's API key was deactivated (soft-deleted / revoked) in the DQC dashboard. This is what sets it apart from the other special responses, which are triggered by runtime conditions rather than by the state of the key:

Special responseWhat triggers it
Deactivated-Key (this page)The survey's DQC API key was deactivated / revoked in the dashboard.
Request-BlockedThe in-browser request was blocked (e.g., ad blocker, or a CORS / CSP policy).
Could not processThe fingerprinting request could not be processed while our infrastructure scales to meet demand.
Submission too quick, data not processedThe respondent advanced through the survey before enough data could be collected.
Wrapper TamperingSession data was tampered with.