API Reference

Authentication

To authenticate requests, the Workiva Admin API uses an OAuth 2.0 Client Credentials Grant implementation. This authentication flow follows three steps:

  1. Obtain a client ID and secret.
  2. To exchange the client ID and secret for a bearer token, make a POST request to the OAuth2/token endpoint.
  3. When accessing the API, authenticate using the bearer token.

The consumer key/secret pair and bearer token grant access to make requests on your behalf. Consider these as sensitive as passwords; do not share or distribute them to untrusted parties.

This manner of authentication is secure only if SSL is used; all requests must use HTTPS.

Make Authenticated Requests

Step 1. Obtain a Client Id and Client Secret

Obtain a client ID and secret by following the instructions here. Have your client ID and secret handy, and store them somewhere safe.

Step 2. Exchange Client Credentials for a Bearer Token

To exchange the client ID and secret for a bearer token, issue an HTTPS POST request to /iam/v1/oauth2/token. This request must include:

  • A Content-Type header with the value of application/x-www-form-urlencoded;charset=UTF-8
  • A body that contains client_id=<your-client-id>, client_secret=<your-client-secret>, and grant_type=client_credentials

Example request

POST /iam/v1/oauth2/token HTTP/1.1
Host: api.app.wdesk.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
client_id=<your-client-id>&client_secret=<your-client-secret>&grant_type=client_credentials

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 19 Jan 2022 19:41:37 GMT
{
    "access_token": "ey...",
    "expires_in": 599,
    "scope": "file:read file:write",
    "token_type": "Bearer"
}

The value associated with the access_token in the response is the bearer token to used to issue requests to Workiva Admin API endpoints.

Step 3. Authenticate API requests with the Bearer Token

To use the bearer token, construct a normal HTTPS request that includes an Authorization header with the value of Bearer <your-bearer-token>.

Example request

GET /platform/v1/spreadsheets/8bd6ec9d30684550b6f6ac30e764cd22
Host: api.app.wdesk.com
Authorization: Bearer ey...

Troubleshooting

  • When making an API request, make sure the Authorization header includes the term Bearer followed by a space before the token value.
  • Workiva bearer tokens expire after 10 minutes. If your script or process takes longer than 10 minutes, you will have to periodically repeat the request to /iam/v1/oauth2/token to get an up-to-date token.