Authentication
Requests to resource endpoints under /v1 need an API key, sent as a bearer token in the Authorization header, and the API version it's written against in the govdash-version header:
curl "$GOVDASH_API_URL/v1/opportunities" \
-H "Authorization: Bearer $GOVDASH_API_KEY" \
-H "govdash-version: $GOVDASH_API_VERSION"const apiVersion = process.env.GOVDASH_API_VERSION
if (!apiVersion) throw new Error("Set GOVDASH_API_VERSION")
const response = await fetch(
`${process.env.GOVDASH_API_URL}/v1/opportunities`,
{
headers: {
Authorization: `Bearer ${process.env.GOVDASH_API_KEY}`,
"govdash-version": apiVersion,
},
},
)
if (!response.ok) throw new Error(await response.text())
console.log(await response.json())import os
import requests
response = requests.get(
f"{os.environ['GOVDASH_API_URL']}/v1/opportunities",
headers={
"Authorization": "Bearer " + os.environ["GOVDASH_API_KEY"],
"govdash-version": os.environ["GOVDASH_API_VERSION"],
},
)
response.raise_for_status()
print(response.json())The API reads the key only from the Authorization header. It doesn't accept keys in query strings or cookies.
API keys
Create a service account for your integration, then create an API key on it in Developer settings. GovDash attributes the integration's changes to this account. Its role controls access, and all of its keys use that role. Keys default to a 90-day expiration. See the Quickstart.
Keys start with gd_live_. GovDash stores only a hash of each key and shows the full key once, when you create it. If you lose a key, create a new one and revoke the old one.
A key stops working when:
- You revoke it. Revoking a key disables it permanently.
- It reaches the expiration you chose.
- Its service account is disabled or removed from the team.
The Last used column in settings updates at most once a minute.
When authentication fails
401 unauthorized
GovDash didn't accept the key. It might be missing, mistyped, cut off, revoked, or expired, or the request might not send it as Authorization: Bearer <key>. The response doesn't say which, so it never helps someone guess a valid key.
{
"error": {
"code": "unauthorized",
"message": "The bearer token is missing or invalid."
}
}Check the key and how your code sends it before you retry. Retrying with the same key gets the same answer.
403 forbidden
GovDash accepted the key, but it can't do what you asked. The most common reason is that the service account's role doesn't include the permission the request needs. A 403 can also mean your team's access to GovDash has ended:
{
"error": {
"code": "forbidden",
"message": "You do not have permission to perform this action."
}
}Read error.message to see which case you hit, then give the service account a role with the permission it needs, or contact your GovDash admin. See Errors.
Rate limits also apply to authentication attempts. See Rate limits if you receive 429 responses.
Next steps
- Keep keys safe and rotate them without downtime. See Security.
- Learn what a key can read based on its classification. See Classification.