Setup#
This page covers what you need before calling the GRC API. The GRC API does not use API Grants — it authenticates with OAuth 2.0 using the Client Credentials Grant. See Authentication for the full flow.
What you need#
A client id and secret. Obtain them as described in Authentication. You do not create or manage an API Grant for this API.
An access token. Exchange the client id and secret for a Bearer token as described in Authentication.
The required scopes for the operations you call:
grc:read— read access to GRC resources (all read operations).grc:write— write access to GRC resources (changing an assurance project’s scope).
The required request headers on every call. See Request headers.
Request headers#
Every call to the GRC API includes the following headers.
Header |
Required |
Description |
|---|---|---|
|
Yes |
|
|
Yes |
Selects the API version. Use |
|
Yes |
The id of the Workiva workspace to operate in. |
|
Recommended |
|
Wk-Workspace selects the tenancy for the request. Authorization is enforced against the
authenticated user’s access within that workspace, so this header is required on every call.
For response headers, see Headers.
Verifying your setup#
Once you have a token and the headers above, list controls to confirm access:
curl -X GET "https://api.app.wdesk.com/controls?\$maxpagesize=1" \
-H "Accept: application/json" \
-H "Authorization: Bearer {access-token}" \
-H "X-Version: 2026-09-01.grc.preview" \
-H "Wk-Workspace: {workspace-id}"
A 200 response with a data array means your client, token, scopes, and headers are all
configured correctly. A 401 indicates a missing or invalid token; a 403 on a list endpoint
indicates the authenticated client lacks access in the given organization and workspace.
Note
Scopes alone do not grant data access. The client must also have access to the GRC data it requests, so grant it the appropriate access in the target organization and workspace before calling the API.