GovDash
Menu

Classification

GovDash labels records with a data classification, and every API key has a classification ceiling. A key can only see and change records at or below its ceiling. This page explains the values, how a key's ceiling works, and what the API does with records above it.

Classification values

ValueMeaning
UNCLASSIFIEDUnclassified data.
CUIControlled Unclassified Information.

Opportunities, contracts, documents, agencies, companies, people, and agent runs all have a classification field.

Your key's ceiling

Each API key has a ceiling of UNCLASSIFIED or CUI, set when the key is created. You can see it in the Classification column of the service account's API keys in settings.

  • An UNCLASSIFIED key reads and writes only UNCLASSIFIED records.
  • A CUI key reads and writes both, as long as its service account has a role with access to CUI data. If the service account loses that access, the key drops to UNCLASSIFIED until it gets it back.

Choose the ceiling when you create the key in settings. It defaults to UNCLASSIFIED. To create a CUI key, you and the service account both need a role with access to CUI data.

Records above the ceiling

A key treats records above its ceiling as if they don't exist. That way the API never confirms that a record you can't read is there.

You do thisResult
List recordsRecords above the ceiling are left out.
Retrieve, update, or delete a record above the ceiling404 not_found, the same response as for an id that doesn't exist.
Create a record with a classification above the ceiling403 forbidden. Nothing is created.

Error responses never mention a record's classification.

Agent runs are the exception to "left out." A run whose work touched data above the key's ceiling still appears, with its status and classification, but its results, failure reason, and inputs are left out.

Setting a classification

You choose a record's classification when you create it.

  • Opportunities, contracts, and agencies: classification is required.
  • Companies and people: classification is optional and defaults to UNCLASSIFIED.
{ "title": "Cloud migration support", "classification": "UNCLASSIFIED" }

You can't change a record's classification through the API yet. PATCH bodies don't accept classification. To reclassify a record, change it in GovDash, where reclassifying also updates the records that depend on it.

Plan for it

  • Send the lowest classification that's accurate for the data.
  • Don't treat a 404 as proof that a record was deleted. It might be above your key's ceiling, or on another team.
  • A sync through an UNCLASSIFIED key doesn't include CUI records. Don't expect the API's counts to match what users see in GovDash.