Amazon WorkMail Workmail Operations API

openapi: 3.2.0
info:
  title: Amazon WorkMail Operations API
  version: '2017-10-01'
  description: Generated from AWS's published Smithy model for Amazon WorkMail. 12 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://workmail.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Operations
paths:
  /#ListGroupsForEntity:
    post:
      operationId: ListGroupsForEntity
      summary: List Groups For Entity
      description: Returns all the groups to which an entity belongs.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ListGroupsForEntityResponse'
        '400':
          description: EntityNotFoundException; EntityStateException; InvalidParameterException; OrganizationNotFoundException; OrganizationStateException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/EntityNotFoundException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - WorkMailService.ListGroupsForEntity
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/ListGroupsForEntityRequest'
      tags:
      - Operations
  /#UpdateGroup:
    post:
      operationId: UpdateGroup
      summary: Update Group
      description: Updates attributes in a group.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/UpdateGroupResponse'
        '400':
          description: EntityNotFoundException; EntityStateException; InvalidParameterException; OrganizationNotFoundException; OrganizationStateException; UnsupportedOperationException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/EntityNotFoundException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - WorkMailService.UpdateGroup
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/UpdateGroupRequest'
      tags:
      - Operations
  /#CreateIdentityCenterApplication:
    post:
      operationId: CreateIdentityCenterApplication
      summary: Create Identity Center Application
      description: Creates the WorkMail application in IAM Identity Center that can be used later in the WorkMail - IdC integration. For more information, see PutIdentityProviderConfiguration. This action does not affect the authentication settings for any WorkMail organizations.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/CreateIdentityCenterApplicationResponse'
        '400':
          description: InvalidParameterException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidParameterException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - WorkMailService.CreateIdentityCenterApplication
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/CreateIdentityCenterApplicationRequest'
      tags:
      - Operations
  /#DeleteIdentityCenterApplication:
    post:
      operationId: DeleteIdentityCenterApplication
      summary: Delete Identity Center Application
      description: Deletes the IAM Identity Center application from WorkMail. This action does not affect the authentication settings for any WorkMail organizations.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DeleteIdentityCenterApplicationResponse'
        '400':
          description: InvalidParameterException; OrganizationStateException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidParameterException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - WorkMailService.DeleteIdentityCenterApplication
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DeleteIdentityCenterApplicationRequest'
      tags:
      - Operations
  /#UpdateUser:
    post:
      operationId: UpdateUser
      summary: Update User
      description: Updates data for the user. To have the latest information, it must be preceded by a DescribeUser call. The dataset in the request should be the one expected when performing another DescribeUser call.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/UpdateUserResponse'
        '400':
          description: DirectoryServiceAuthenticationFailedException; DirectoryUnavailableException; EntityNotFoundException; EntityStateException; InvalidParameterException; OrganizationNotFoundException; OrganizationStateException; UnsupportedOperationException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DirectoryServiceAuthenticationFailedException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - WorkMailService.UpdateUser
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
      tags:
      - Operations
  /#DeletePersonalAccessToken:
    post:
      operationId: DeletePersonalAccessToken
      summary: Delete Personal Access Token
      description: Deletes the Personal Access Token from the provided WorkMail Organization.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DeletePersonalAccessTokenResponse'
        '400':
          description: InvalidParameterException; OrganizationNotFoundException; OrganizationStateException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidParameterException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - WorkMailService.DeletePersonalAccessToken
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DeletePersonalAccessTokenRequest'
      tags:
      - Operations
  /#ListPersonalAccessTokens:
    post:
      operationId: ListPersonalAccessTokens
      summary: List Personal Access Tokens
      description: Returns a summary of your Personal Access Tokens.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ListPersonalAccessTokensResponse'
        '400':
          description: EntityNotFoundException; EntityStateException; InvalidParameterException; OrganizationNotFoundException; OrganizationStateException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/EntityNotFoundException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - WorkMailService.ListPersonalAccessTokens
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/ListPersonalAccessTokensRequest'
      tags:
      - Operations
  /#DescribeEntity:
    post:
      operationId: DescribeEntity
      summary: Describe Entity
      description: Returns basic details about an entity in WorkMail.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DescribeEntityResponse'
        '400':
          description: EntityNotFoundException; InvalidParameterException; OrganizationNotFoundException; OrganizationStateException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/EntityNotFoundException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - WorkMailService.DescribeEntity
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DescribeEntityRequest'
      tags:
      - Operations
  /#GetPersonalAccessTokenMetadata:
    post:
      operationId: GetPersonalAccessTokenMetadata
      summary: Get Personal Access Token Metadata
      description: Requests details of a specific Personal Access Token within the WorkMail organization.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/GetPersonalAccessTokenMetadataResponse'
        '400':
          description: InvalidParameterException; OrganizationNotFoundException; OrganizationStateException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidParameterException'
        '404':
          description: ResourceNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - WorkMailService.GetPersonalAccessTokenMetadata
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/GetPersonalAccessTokenMetadataRequest'
      tags:
      - Operations
components:
  schemas:
    EntityNotFoundException:
      type: object
      properties:
        Message:
          type: string
    InvalidParameterException:
      type: object
      properties:
        Message:
          type: string
    ListGroupsForEntityResponse:
      type: object
      properties:
        Groups:
          type: array
          items:
            $ref: '#/components/schemas/GroupIdentifier'
          description: The overview of groups in an organization.
        NextToken:
          type: string
          description: The token to use to retrieve the next page of results. This value is `null` when there are no more results to return.
    DirectoryServiceAuthenticationFailedException:
      type: object
      properties:
        Message:
          type: string
    UpdateUserResponse:
      type: object
      properties: {}
    DeleteIdentityCenterApplicationRequest:
      type: object
      properties:
        ApplicationArn:
          type: string
          description: The Amazon Resource Name (ARN) of the application.
      required:
      - ApplicationArn
    GetPersonalAccessTokenMetadataRequest:
      type: object
      properties:
        OrganizationId:
          type: string
          description: The Organization ID.
        PersonalAccessTokenId:
          type: string
          description: The Personal Access Token ID.
      required:
      - OrganizationId
      - PersonalAccessTokenId
    DeletePersonalAccessTokenResponse:
      type: object
      properties: {}
    ResourceNotFoundException:
      type: object
      properties:
        Message:
          type: string
    DescribeEntityRequest:
      type: object
      properties:
        OrganizationId:
          type: string
          description: The identifier for the organization under which the entity exists.
        Email:
          type: string
          description: The email under which the entity exists.
      required:
      - OrganizationId
      - Email
    DeletePersonalAccessTokenRequest:
      type: object
      properties:
        OrganizationId:
          type: string
          description: The Organization ID.
        PersonalAccessTokenId:
          type: string
          description: The Personal Access Token ID.
      required:
      - OrganizationId
      - PersonalAccessTokenId
    ListGroupsForEntityFilters:
      type: object
      properties:
        GroupNamePrefix:
          type: string
          description: Filters only group names that start with the provided name prefix.
    ListPersonalAccessTokensRequest:
      type: object
      properties:
        OrganizationId:
          type: string
          description: The Organization ID.
        UserId:
          type: string
          description: The WorkMail User ID.
        NextToken:
          type: string
          description: The token from the previous response to query the next page.
        MaxResults:
          type: integer
          description: The maximum amount of items that should be returned in a response.
      required:
      - OrganizationId
    UpdateGroupResponse:
      type: object
      properties: {}
    UpdateUserRequest:
      type: object
      properties:
        OrganizationId:
          type: string
          description: The identifier for the organization under which the user exists.
        UserId:
          type: string
          description: 'The identifier for the user to be updated. The identifier can be the UserId, Username, or email. The following identity formats are available: User ID: 12345678-1234-1234-1234-123456789012 or S-1-1-12-1234567890-123456789-123456789-1234 Email address: user@domain.tld User name: user'
        Role:
          type: string
          enum:
          - USER
          - RESOURCE
          - SYSTEM_USER
          - REMOTE_USER
          description: Updates the user role. You cannot pass SYSTEM_USER or RESOURCE.
        DisplayName:
          type: string
          description: Updates the display name of the user.
        FirstName:
          type: string
          description: Updates the user's first name.
        LastName:
          type: string
          description: Updates the user's last name.
        HiddenFromGlobalAddressList:
          type: boolean
          description: If enabled, the user is hidden from the global address list.
        Initials:
          type: string
          description: Updates the user's initials.
        Telephone:
          type: string
          description: Updates the user's contact details.
        Street:
          type: string
          description: Updates the user's street address.
        JobTitle:
          type: string
          description: Updates the user's job title.
        City:
          type: string
          description: Updates the user's city.
        Company:
          type: string
          description: Updates the user's company.
        ZipCode:
          type: string
          description: Updates the user's zip code.
        Department:
          type: string
          description: Updates the user's department.
        Country:
          type: string
          description: Updates the user's country.
        Office:
          type: string
          description: Updates the user's office.
        IdentityProviderUserId:
          type: string
          description: User ID from the IAM Identity Center. If this parameter is empty it will be updated automatically when the user logs in for the first time to the mailbox associated with WorkMail.
      required:
      - OrganizationId
      - UserId
    ListPersonalAccessTokensResponse:
      type: object
      properties:
        NextToken:
          type: string
          description: The token from the previous response to query the next page.
        PersonalAccessTokenSummaries:
          type: array
          items:
            $ref: '#/components/schemas/PersonalAccessTokenSummary'
          description: Lists all the personal tokens in an organization or user, if user ID is provided.
    GroupIdentifier:
      type: object
      properties:
        GroupId:
          type: string
          description: Group ID that matched the group.
        GroupName:
          type: string
          description: Group name that matched the group.
    DescribeEntityResponse:
      type: object
      properties:
        EntityId:
          type: string
          description: The entity ID under which the entity exists.
        Name:
          type: string
          description: Username, GroupName, or ResourceName based on entity type.
        Type:
          type: string
          enum:
          - GROUP
          - USER
          - RESOURCE
          description: Entity type.
    GetPersonalAccessTokenMetadataResponse:
      type: object
      properties:
        PersonalAccessTokenId:
          type: string
          description: The Personal Access Token ID.
        UserId:
          type: string
          description: The WorkMail User ID.
        Name:
          type: string
          description: The Personal Access Token name.
        DateCreated:
          type: string
          format: date-time
          description: The date when the Personal Access Token ID was created.
        DateLastUsed:
          type: string
          format: date-time
          description: The date when the Personal Access Token ID was last used.
        ExpiresTime:
          type: string
          format: date-time
          description: The time when the Personal Access Token ID will expire.
        Scopes:
          type: array
          items:
            type: string
          description: Lists all the Personal Access Token permissions for a mailbox.
    UpdateGroupRequest:
      type: object
      properties:
        OrganizationId:
          type: string
          description: The identifier for the organization under which the group exists.
        GroupId:
          type: string
          description: 'The identifier for the group to be updated. The identifier can accept GroupId, Groupname, or email. The following identity formats are available: Group ID: 12345678-1234-1234-1234-123456789012 or S-1-1-12-1234567890-123456789-123456789-1234 Email address: group@domain.tld Group name: group'
        HiddenFromGlobalAddressList:
          type: boolean
          description: If enabled, the group is hidden from the global address list.
      required:
      - OrganizationId
      - GroupId
    CreateIdentityCenterApplicationResponse:
      type: object
      properties:
        ApplicationArn:
          type: string
          description: The Amazon Resource Name (ARN) of the application.
    CreateIdentityCenterApplicationRequest:
      type: object
      properties:
        Name:
          type: string
          description: The name of the IAM Identity Center application.
        InstanceArn:
          type: string
          description: The Amazon Resource Name (ARN) of the instance.
        ClientToken:
          type: string
          description: The idempotency token associated with the request.
      required:
      - Name
      - InstanceArn
    PersonalAccessTokenSummary:
      type: object
      properties:
        PersonalAccessTokenId:
          type: string
          description: The ID of the Personal Access Token.
        UserId:
          type: string
          description: The user ID of the WorkMail user associated with the Personal Access Token.
        Name:
          type: string
          description: The name of the Personal Access Token.
        DateCreated:
          type: string
          format: date-time
          description: The date when the Personal Access Token was created.
        DateLastUsed:
          type: string
          format: date-time
          description: The date when the Personal Access Token was last used.
        ExpiresTime:
          type: string
          format: date-time
          description: The date when the Personal Access Token will expire.
        Scopes:
          type: array
          items:
            type: string
          description: Lists all the Personal Access Token permissions for a mailbox.
    DeleteIdentityCenterApplicationResponse:
      type: object
      properties: {}
    ListGroupsForEntityRequest:
      type: object
      properties:
        OrganizationId:
          type: string
          description: The identifier for the organization under which the entity exists.
        EntityId:
          type: string
          description: 'The identifier for the entity. The entity ID can accept UserId or GroupID, Username or Groupname, or email. Entity ID: 12345678-1234-1234-1234-123456789012 or S-1-1-12-1234567890-123456789-123456789-1234 Email address: entity@domain.tld Entity name: entity'
        Filters:
          $ref: '#/components/schemas/ListGroupsForEntityFilters'
        NextToken:
          type: string
          description: The token to use to retrieve the next page of results. The first call does not contain any tokens.
        MaxResults:
          type: integer
          description: The maximum number of results to return in a single call.
      required:
      - OrganizationId
      - EntityId
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: workmail
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/workmail/service/2017-10-01/workmail-2017-10-01.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)