Ctrl+K

Authentication

Authentication#

To authenticate requests, the Workiva 2022-01-01 (default) 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 one of

    • application/x-www-form-urlencoded;charset=UTF-8

    • application/json

  • A body that contains client_id=<your-client-id>, client_secret=<your-client-secret>, and grant_type=client_credentials

Example request (using x-www-form-urlencoded)

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 request (using application/json)

POST /iam/v1/oauth2/token HTTP/1.1
Host: api.app.wdesk.com
Content-Type: application/json

{"grant_type": "client_credentials", "client_id": "<your-client-id>", "client_secret": "<your-client-secret>" }

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 2022-01-01 (default) 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.