openapi: 3.0.1
info:
  title: IAM Account API Specification
  description: This specification describes the endpoints of the IAM Account Service.
  version: 0-SNAPSHOT
servers:
- url: http://localhost
  description: local development host
tags:
- name: IAM Console - Account
  description: Management functions for accounts
paths:
  /account/v1/accounts:
    post:
      tags:
      - IAM Console - Account
      summary: Create account
      description: Register new account
      operationId: createAccount
      parameters:
      - $ref: "#/components/parameters/Idp-Key"
      - $ref: "#/components/parameters/Captcha-Token"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccountInV1"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountV1"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
      security:
      - external-token: []
  /account/v1/accounts/{account-expression}:
    get:
      tags:
      - IAM Console - Account
      summary: Get account by account expression
      description: Read account information by account expression
      operationId: getAccountByExpression
      parameters:
      - $ref: "#/components/parameters/account-expression"
      - name: projection
        in: query
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccountProjectionV1"
      responses:
        "200":
          description: OK
          headers:
            Data-Projected:
              $ref: "#/components/headers/Data-Projected"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountV1"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
      - iam-console-token: []
  /account/v1/accounts/{account-expression}/~decommission:
    post:
      tags:
      - IAM Console - Account
      summary: Decommission account
      description: "Decommission account, purging data where possible for all applications\
        \ and associated tenants"
      operationId: decommissionAccount
      parameters:
      - $ref: "#/components/parameters/account-expression"
      - $ref: "#/components/parameters/returnUpdated"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountV1"
        "204":
          $ref: "#/components/responses/NoContent"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
      security:
      - iam-console-token: []
  /account/v1/accounts/{account-expression}/description:
    put:
      tags:
      - IAM Console - Account
      summary: Set account description
      description: Updates the account description
      operationId: setAccountDescription
      parameters:
      - $ref: "#/components/parameters/account-expression"
      - $ref: "#/components/parameters/returnUpdated"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DescriptionValueInV1"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountV1"
        "204":
          $ref: "#/components/responses/NoContent"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
      - iam-console-token: []
    delete:
      tags:
      - IAM Console - Account
      summary: Delete account description
      description: Removes the account description
      operationId: deleteAccountDescription
      parameters:
      - $ref: "#/components/parameters/account-expression"
      - $ref: "#/components/parameters/returnUpdated"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountV1"
        "204":
          $ref: "#/components/responses/NoContent"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
      - iam-console-token: []
  /account/v1/accounts/{account-expression}/name:
    put:
      tags:
      - IAM Console - Account
      summary: Set account name
      description: Updates the name of the account
      operationId: setAccountName
      parameters:
      - $ref: "#/components/parameters/account-expression"
      - $ref: "#/components/parameters/returnUpdated"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NameRequiredValueInV1"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountV1"
        "204":
          $ref: "#/components/responses/NoContent"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
      - iam-console-token: []
  /account/v1/accounts/{account-expression}/tags/{tag}:
    put:
      tags:
      - IAM Console - Account
      summary: Set account tag
      description: Sets a tag for the given account
      operationId: setAccountTag
      parameters:
      - $ref: "#/components/parameters/account-expression"
      - $ref: "#/components/parameters/tag"
      - $ref: "#/components/parameters/returnUpdated"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountV1"
        "204":
          $ref: "#/components/responses/NoContent"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
      security:
      - iam-console-token: []
    delete:
      tags:
      - IAM Console - Account
      summary: Delete account tag
      description: Removes given tag for the given account
      operationId: deleteAccountTag
      parameters:
      - $ref: "#/components/parameters/account-expression"
      - $ref: "#/components/parameters/tag"
      - $ref: "#/components/parameters/returnUpdated"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountV1"
        "204":
          $ref: "#/components/responses/NoContent"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
      security:
      - iam-console-token: []
components:
  schemas:
    AccountInV1:
      required:
      - name
      type: object
      properties:
        accountIdPrefix:
          maxLength: 16
          pattern: "^[a-zA-Z0-9-_&|#%?<>./:;,!\\[\\]()]{0,16}$"
          type: string
          description: This optional field can be used to give a prefix for the accountId
            which is about to be created
          example: Company
        name:
          maxLength: 64
          minLength: 1
          type: string
          description: "A name, usually for an entity"
          example: John Doe
        description:
          maxLength: 4096
          type: string
          description: "A description, usually for an entity"
          example: "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
        tags:
          maxItems: 10
          minItems: 0
          type: array
          description: A set of tags. Any duplicates will be merged.
          items:
            maxLength: 20
            minLength: 1
            type: string
            description: A label that can be used to distinguish or group an entity
            example: RED
        accountOwner:
          $ref: "#/components/schemas/AccountOwner"
      description: Account and owner registration details
    AccountOwner:
      type: object
      properties:
        name:
          maxLength: 64
          type: string
          description: "A name, usually for an entity"
          example: John Doe
        avatar:
          $ref: "#/components/schemas/AdministratorAvatarInV1"
      description: Details about the user which registered this account
    AccountProjectionV1:
      type: object
      properties:
        name:
          $ref: "#/components/schemas/FieldProjectionV1"
        description:
          $ref: "#/components/schemas/FieldProjectionV1"
        tags:
          $ref: "#/components/schemas/FieldProjectionV1"
        status:
          $ref: "#/components/schemas/FieldProjectionV1"
        createdAt:
          $ref: "#/components/schemas/FieldProjectionV1"
        createdBy:
          $ref: "#/components/schemas/FieldProjectionV1"
        lastModifiedAt:
          $ref: "#/components/schemas/FieldProjectionV1"
        lastModifiedBy:
          $ref: "#/components/schemas/FieldProjectionV1"
    AccountV1:
      required:
      - accountId
      - changeId
      - createdAt
      - createdBy
      - lastModifiedAt
      - lastModifiedBy
      - name
      - status
      type: object
      properties:
        accountId:
          type: string
          description: The globally unique identifier for an account
        name:
          type: string
          description: "A name, usually for an entity"
          example: John Doe
        description:
          type: string
          description: "A description, usually for an entity"
          example: "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
        status:
          type: string
          description: The current status of the account
        tags:
          type: array
          description: A set of tags
          items:
            type: string
            description: A label that can be used to distinguish or group an entity
            example: RED
        createdAt:
          type: string
          description: UTC date time when entity was created. This string is formatted
            according to RFC3339.
          format: date-time
        createdBy:
          type: string
          description: The globally unique identifier for an actor
          example: user-6825a22e225146801209c9fe
        lastModifiedAt:
          type: string
          description: UTC date time when entity was modified. This string is formatted
            according to RFC3339.
          format: date-time
        lastModifiedBy:
          type: string
          description: The globally unique identifier for an actor
          example: user-6825a22e225146801209c9fe
        changeId:
          type: string
          description: Text representation of changeId sequence number
          example: "7380283282446876762"
      description: IAM Account details
    AdministratorAvatarInV1:
      type: object
      properties:
        avatarUri:
          type: string
          description: An image uri to use as the avatar image for an administrator
          format: uri
      description: Avatar configuration
    DescriptionValueInV1:
      type: object
      properties:
        description:
          maxLength: 4096
          type: string
          description: "A description, usually for an entity"
          example: "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
      description: Envelope message for updating a description
    ErrorDetailV1:
      type: object
      properties:
        field:
          type: string
          description: A reference to a field or parameter which cannot be processed.
        value:
          type: string
          description: The value which could not be processed.
        message:
          type: string
          description: A human readable message of error. Intended for developers.
      description: 'Additional information about the error '
    ErrorV1:
      required:
      - errorId
      - occurredAt
      type: object
      properties:
        errorId:
          type: string
          description: "An error identifier for the request, to be provided in troubleshooting."
        code:
          type: string
          description: |-
            An error code which describes this error. Documented per service and endpoint.
            See respective ErrorCodeRegistry DTO for possible error codes.
        message:
          type: string
          description: A human readable message of error. Intended for developers.
        details:
          type: array
          description: Additional information about the error which can be used in
            troubleshooting.
          items:
            $ref: "#/components/schemas/ErrorDetailV1"
        occurredAt:
          type: string
          description: The timestamp when the error occurred. This string is formatted
            according to RFC3339.
          format: date-time
    FieldProjectionV1:
      type: object
      properties:
        mode:
          $ref: "#/components/schemas/ProjectionModeTypeV1"
      description: Field projection settings
    IamAccountErrorCodeRegistryV1:
      type: object
      properties:
        createAccount:
          type: string
          enum:
          - INPUT_MALFORMED
          - AUTHENTICATION_FAILED
          - AUTHENTICATION_EXPIRED
          - AUTHENTICATION_REVOKED
          - AUTHENTICATION_IDP_NOT_FOUND
          - AUTHORIZATION_INVALID_CAPTCHA
          - INPUT_TOO_MANY_REQUESTS
        getAccount:
          type: string
          enum:
          - INPUT_MALFORMED
          - AUTHENTICATION_FAILED
          - AUTHENTICATION_EXPIRED
          - AUTHENTICATION_REVOKED
          - AUTHENTICATION_INVALID_APPLICATION
          - AUTHORIZATION_MISSING_PERMISSION
          - IAM_ACCOUNT_NOT_FOUND
        setAccountName:
          type: string
          enum:
          - INPUT_MALFORMED
          - AUTHENTICATION_FAILED
          - AUTHENTICATION_EXPIRED
          - AUTHENTICATION_REVOKED
          - AUTHENTICATION_INVALID_APPLICATION
          - AUTHORIZATION_MISSING_PERMISSION
          - IAM_ACCOUNT_NOT_FOUND
        setAccountDescription:
          type: string
          enum:
          - INPUT_MALFORMED
          - AUTHENTICATION_FAILED
          - AUTHENTICATION_EXPIRED
          - AUTHENTICATION_REVOKED
          - AUTHENTICATION_INVALID_APPLICATION
          - AUTHORIZATION_MISSING_PERMISSION
          - IAM_ACCOUNT_NOT_FOUND
        deleteAccountDescription:
          type: string
          enum:
          - INPUT_MALFORMED
          - AUTHENTICATION_FAILED
          - AUTHENTICATION_EXPIRED
          - AUTHENTICATION_REVOKED
          - AUTHENTICATION_INVALID_APPLICATION
          - AUTHORIZATION_MISSING_PERMISSION
          - IAM_ACCOUNT_NOT_FOUND
        setAccountTag:
          type: string
          enum:
          - INPUT_MALFORMED
          - AUTHENTICATION_FAILED
          - AUTHENTICATION_EXPIRED
          - AUTHENTICATION_REVOKED
          - AUTHENTICATION_INVALID_APPLICATION
          - AUTHORIZATION_MISSING_PERMISSION
          - IAM_ACCOUNT_NOT_FOUND
          - IAM_TAG_LIMIT_EXCEEDED
        deleteAccountTag:
          type: string
          enum:
          - INPUT_MALFORMED
          - AUTHENTICATION_FAILED
          - AUTHENTICATION_EXPIRED
          - AUTHENTICATION_REVOKED
          - AUTHENTICATION_INVALID_APPLICATION
          - AUTHORIZATION_MISSING_PERMISSION
          - IAM_ACCOUNT_NOT_FOUND
        decommissionAccount:
          type: string
          enum:
          - INPUT_MALFORMED
          - AUTHENTICATION_FAILED
          - AUTHENTICATION_EXPIRED
          - AUTHENTICATION_REVOKED
          - AUTHENTICATION_INVALID_APPLICATION
          - AUTHORIZATION_MISSING_PERMISSION
          - IAM_ACCOUNT_NOT_FOUND
      description: |-
        This entry describes possible error codes that may be returned by their respective operation.
        These can be used to apply logic upon receiving an error response.
    NameRequiredValueInV1:
      required:
      - name
      type: object
      properties:
        name:
          maxLength: 64
          minLength: 1
          type: string
          description: "A name, usually for an entity"
          example: John Doe
      description: Envelope message for updating a name
    ProjectionModeTypeV1:
      type: string
      description: Indicates if the field shall be included in the result. Defaults
        to INCLUDE if omitted.
      default: INCLUDE
      enum:
      - INCLUDE
      - EXCLUDE
  responses:
    NoContent:
      description: The request is processed and no content was returned
    BadRequest:
      description: "The request is malformed, see error data for additional information"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorV1"
    Unauthorized:
      description: The request did not have valid authentication credentials
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorV1"
    Forbidden:
      description: The requester is not authorized to perform this action
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorV1"
    NotFound:
      description: The resource could not be found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorV1"
    Conflict:
      description: "The request could not be processed due to a conflict in state,\
        \ see error data for additional information"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorV1"
  parameters:
    Captcha-Token:
      name: Captcha-Token
      in: header
      required: false
      schema:
        maxLength: 4096
        type: string
        description: Captcha token to verify that the request is not made by a bot
    Idp-Key:
      name: Idp-Key
      in: header
      required: true
      schema:
        maxLength: 64
        minLength: 1
        pattern: "^[a-zA-Z0-9-_.]{1,64}$"
        type: string
        description: An identity provider key which is used to identity a specific
          identity provider configuration.
        example: idp-1
    account-expression:
      name: account-expression
      in: path
      required: true
      schema:
        pattern: "^current$|^[a-zA-Z0-9-_.]{1,64}$"
        type: string
        description: "Used to identify a specific accountId. The available options\
          \ are: \n* 'current' - the accountId specified by provided authentication\
          \ token\n* '{accountId}' - direct accountId reference"
    returnUpdated:
      name: returnUpdated
      in: query
      description: To return the entity after successful update or not
      schema:
        type: boolean
        default: false
    tag:
      name: tag
      in: path
      required: true
      schema:
        maxLength: 20
        minLength: 1
        type: string
        description: A label that can be used to distinguish or group an entity
        example: RED
  headers:
    Data-Projected:
      description: States if the returned data was projected. Defaults to 'false'
        if omitted
      required: false
      schema:
        type: boolean
    Idp-Key:
      description: IdpKey to be used when matching given credentials for the current
        application idp configurations
      required: true
      schema:
        pattern: "^[a-zA-Z0-9-_.]{1,64}$"
        type: string
  securitySchemes:
    external-token:
      type: http
      scheme: bearer
      bearerFormat: External token issued by a trusted identity provider
    iam-console-token:
      type: http
      scheme: bearer
      bearerFormat: IAM issued jwt token for the IAM console application