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'