openapi: 3.0.2
info:
title: IAM Services
description: |
Authorization and authentication endpoints for accessing the Workiva Developer APIs.
version: v1
contact:
name: Workiva Inc
url: 'https://www.workiva.com'
email: platformsupport@workiva.com
termsOfService: 'https://developers.workiva.com'
servers:
- url: 'https://api.app.wdesk.com/iam/v1'
description: US
- url: 'https://api.eu.wdesk.com/iam/v1'
description: EU
externalDocs:
description: Developer documentation for Workiva Inc.
url: 'https://developers.workiva.com'
tags:
- name: IAM
components:
schemas:
BearerToken:
description: |
[Bearer token](ref:iam-helpers#bearertoken) to use in subsequent requests to the Workiva APIs.
type: object
properties:
access_token:
description: The opaque string used to authorize and make requests on behalf of the user
type: string
expires_in:
description: The number of seconds the access token is valid
type: integer
token_type:
description: The type of access token; typically bearer
type: string
scope:
description: 'The limits of the user''s access with the token, such as Read or Create'
type: string
required:
- access_token
- expires_in
- token_type
- scope
Error:
description: Error response object containing an error code.
type: object
properties:
error:
description: |
The possible `error` codes are:
- `invalid_request` - The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
- `unauthorized_client` - The client is not authorized to request an authorization code using this method.
- `access_denied` - The resource owner or authorization server denied the request.
- `unsupported_response_type` - The authorization server does not support obtaining an authorization code using this method.
- `invalid_scope` - The requested scope is invalid, unknown, or malformed.
- `server_error` - The authorization server encountered an unexpected condition that prevented it from fulfilling the request.
- `temporarily_unavailable` - The authorization server is currently unable to handle
the request due to a temporary overloading or maintenance of the server.
type: string
error_description:
description: Human-readable ASCII text providing additional information.
type: string
error_uri:
description: |
A URI identifying a human-readable web page with information about the error.
type: string
securitySchemes:
basic:
description: Basic authentication using the Authorization HTTP header.
type: http
scheme: basic
paths:
/oauth2/token:
post:
operationId: tokenRequest
summary: Retrieve a token
description: |
The preferred authentication method is to include an Authorization header with the value of Basic `` in your request. The body of the request must be `grant_type=client_credentials`.
If your user agent cannot set the Authorization header, you may include the client_id and client_secret in the body of the request as form encoded parameters. The body of the request would then be `grant_type=client_credentials&client_id=&client_secret=`.
The client can optionally specify a `scope` parameter to limit the scope of the returned [access token](ref:iam-helpers#bearertoken). In turn, the server uses a `scope` response parameter to inform the client of the scope of the actual access token issued. The actual `scope` returned may not match the `scope` requested.
Subsequent requests to Workiva APIs are authorized using the bearer token.
tags:
- IAM
security:
- basic: []
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
grant_type:
description: The grant type for the Bearer token. Must be client_credentials.
type: string
format: ^client_credentials$
client_id:
description: A previously obtained client id.
type: string
client_secret:
description: A previously obtained client secret.
type: string
scope:
description: The scope of the access request.
type: string
required:
- grant_type
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BearerToken'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'