API Reference

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

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

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 19 Jan 2017 19:41:37 GMT
    "access_token": "ey...",
    "expires_in": 599,
    "scope": "data_tables|r data_tables|w",
    "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 /spreadsheets/<version>/spreadsheet/12345
Host: api.app.wdesk.com
Authorization: Bearer ey...