swagger.yaml

swagger: "2.0"
info:
  title: dp-identity-api
  description: "An API used to manage the authorisation of users accessing data publishing services."
  version: 1.0.0
  license:
    name: "Open Government Licence v3.0"
    url: "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/"
basePath: "/v1"
schemes:
  - http
paths:
  /tokens:
    post:
      tags:
        - Tokens
      summary: "Creates tokens for authorisation, ID and refresh for authenticated users"
      security: []
      consumes:
        - application/json
      parameters:
        - in: body
          name: user
          description: "The email and password for a user"
          schema:
            type: object
            required:
              - email
              - password
            properties:
              email:
                type: string
              password:
                type: string
          required: true
      responses:
        201:
          description: "Created"
          headers:
            Authorization:
              type: string
              description: "Auth token"
            ID:
              type: string
              description: "ID token"
            Refresh:
              type: string
              description: "Refresh token"
          schema:
            $ref: '#/definitions/SignInExpirationTime'
        400:
          $ref: '#/responses/BadRequestError'
        401:
          $ref: '#/responses/UnauthorizedError'
        403:
          description: "Forbidden. Too many login attempts"
          schema:
            $ref: '#/definitions/ErrorList'
        500:
          $ref: '#/responses/InternalError'
    delete:
      security:
        - Authorization: []
      tags:
        - Tokens
      summary: "Enables functionality to logout all active users"
      consumes:
        - application/json
      responses:
        202:
          description: "Request Accepted"
        401:
          $ref: '#/responses/UnauthorizedError'
        500:
          $ref: '#/responses/InternalError'
  /tokens/self:
    put:
      tags:
        - Tokens
      summary: "Refreshes a users access token using the refresh and ID tokens"
      security: []
      consumes:
        - application/json
      parameters:
        - in: header
          type: string
          name: ID
          description: "The users ID token"
          required: true
        - in: header
          type: string
          name: Refresh
          description: "The users refresh token"
          required: true
      responses:
        201:
          description: "Created"
          headers:
            Authorization:
              type: string
              description: "Auth token"
            ID:
              type: string
              description: "ID token"
            Refresh:
              type: string
              description: "Refresh token"
          schema:
            $ref: '#/definitions/ExpirationTime'
        400:
          $ref: '#/responses/BadRequestError'
        403:
          description: "Forbidden. Expired or invalid refresh token"
          schema:
            $ref: '#/definitions/ErrorList'
        500:
          $ref: '#/responses/InternalError'
    delete:
      tags:
        - Tokens
      summary: "Signs out a user, invalidating their access tokens"
      security: []
      consumes:
        - application/json
      parameters:
        - in: header
          type: string
          name: Authorization
          description: "The users access token as bearer token"
          required: true
      responses:
        204:
          description: "No Content - Successful sign out"
        400:
          description: "Invalid request. Missing, malformed or invalid access token provided"
          schema:
            $ref: '#/definitions/ErrorList'
        500:
          $ref: '#/responses/InternalError'
  /users:
    get:
      tags:
        - Users
      summary: "List users"
      description: "List all the user in the user pool"
      security:
        - Authorization: []
      parameters:
        - in: query
          name: active
          type: boolean
          description: filter on user active state.
        - in: query
          name: sort
          type: string
          default: id:asc
          description: |
            If the key or direction are not in the enum list below, sort will default.
            The sort parameter allows multiple keys and direction, which should be supplied in a comma
            separated string.
          enum:
            - forename
            - forename:asc
            - forename:desc
            - lastname
            - lastname:asc
            - lastname:desc
            - email
            - email:asc
            - email:desc
            - id
            - id:asc
            - id:desc
      produces:
        - "application/json"
      responses:
        200:
          description: "The list of users"
          schema:
            $ref: '#/definitions/UserList'
        400:
          $ref: '#/responses/BadRequestError'
        401:
          $ref: '#/responses/UnauthorizedError'
        500:
          $ref: '#/responses/InternalError'
    post:
      tags:
        - Users
      summary: "Creates a new user"
      description: "Creates a new user in cognito"
      security:
        - Authorization: []
      consumes:
        - application/json
      produces:
        - "application/json"
      parameters:
        - in: body
          name: user
          description: "The forename, surname and email for a user."
          schema:
            required: 
              - "forename"
              - "lastname"
              - "email"
            type: object
            properties:
              forename:
                type: string
                example: "bob"
              lastname:
                type: string
                example: "bobbings"
              email:
                type: string
                example: "email@ons.gov.uk"
          required: true
      responses:
        201:
          description: "The user is created"
          schema:
            $ref: '#/definitions/User'
        400:
          $ref: '#/responses/BadRequestError'
        401:
          $ref: '#/responses/UnauthorizedError'
        500:
          $ref: '#/responses/InternalError'
  /users/{id}:
    get:
      tags:
        - Users
      summary: "Get a user"
      description: "Gets the details of a user from the user pool"
      security:
        - Authorization: []
      parameters:
        - in: path
          name: id
          type: string
          required: true
          description: the users id
      produces:
        - "application/json"
      responses:
        200:
          description: "The users details"
          schema:
            $ref: '#/definitions/User'
        401:
          $ref: '#/responses/UnauthorizedError'
        404:
          description: "User not found"
          schema:
            $ref: '#/definitions/ErrorList'
        500:
          $ref: '#/responses/InternalError'
    put:
      tags:
        - Users
      summary: "Update a user"
      description: "Updates the details of a user in the user pool"
      security:
        - Authorization: []
      parameters:
        - in: path
          name: id
          type: string
          required: true
          description: the users id
        - in: body
          name: user
          description: "The forename, surname, active status and status notes for a user."
          schema:
            required: 
              - "forename"
              - "lastname"
              - "active"
            type: object
            properties:
              forename:
                type: string
                example: "bob"
              lastname:
                type: string
                example: "bobbings"
              active:
                type: boolean
              status_notes:
                type: string
                example: "User has been suspended"
      responses:
        200:
          description: "The users details"
          schema:
            $ref: '#/definitions/User'
        400:
          $ref: '#/responses/BadRequestError'
        401:
          $ref: '#/responses/UnauthorizedError'
        404:
          description: "User not found"
          schema:
            $ref: '#/definitions/ErrorList'
        500:
          $ref: '#/responses/InternalError'
  /users/{id}/password:
    post:
      tags:
        - Users
      summary: "Sets a generated password for a user"
      description: "Sets a generated password for a user"
      security:
        - Authorization: []
      parameters:
        - in: path
          name: id
          type: string
          required: true
          description: the users id
      responses:
        202:
          description: "Password setting processed"
        400:
          $ref: '#/responses/BadRequestError'
        401:
          $ref: '#/responses/UnauthorizedError'
        404:
          description: "User not found"
          schema:
            $ref: '#/definitions/ErrorList'
        500:
          $ref: '#/responses/InternalError'
  /users/{id}/groups:
    get:
      tags:
        - Users
      summary: "Get groups for a user"
      description: "Gets the details of groups that a given user is a member"
      security:
        - Authorization: []
      parameters:
        - in: path
          name: id
          type: string
          required: true
          description: the users id
      produces:
        - "application/json"
      responses:
        200:
          description: "The user groups details"
          schema:
            $ref: '#/definitions/GroupList'
        401:
          $ref: '#/responses/UnauthorizedError'
        404:
          description: "User not found"
          schema:
            $ref: '#/definitions/ErrorList'
        500:
          $ref: '#/responses/InternalError'
  /users/self/password:
    put:
      tags:
        - Users
      summary: "Changes the user's password"
      description: "Changes the user's password in Cognito"
      security: []
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: body
          name: "Change password request"
          description: "The type of change request, email address, new password and session.
                        for type ForgottenPassword email address, new password and verification token"
          schema:
            required: 
              - "type"
              - "email"
              - "password"
            type: object
            properties:
              type:
                type: string
                example: "NewPasswordRequired"
                enum:
                  - "NewPasswordRequired"
                  - "ForgottenPassword"
              email:
                type: string
                example: "email@ons.gov.uk"
              password:
                type: string
              session:
                type: string
                description: "Required if type is NewPasswordRequired"
              verification_token:
                type: string
                description: "Required if type is ForgottenPassword"
          required: true
      responses:
        202:
          description: "Password changed"
          headers:
            Authorization:
              type: string
              description: "Auth token"
            ID:
              type: string
              description: "ID token"
            Refresh:
              type: string
              description: "Refresh token"
          schema:
            $ref: '#/definitions/PasswordResetExpirationTime'
        400:
          $ref: '#/responses/BadRequestError'
        500:
          $ref: '#/responses/InternalError'
        501:
          description: "Requested unimplemented password change type"
          schema:
            $ref: '#/definitions/ErrorList'
  /password-reset:
    post:
      tags:
        - Users
      summary: "Sends the user a password reset email"
      description: "Trigger a password reset email from Cognito"
      security: []
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: body
          name: "Password reset request"
          description: "The email address for the user resetting their password"
          required: true
          schema:
            required: 
              - "email"
            type: object
            properties:
              email:
                type: string
                example: "email@ons.gov.uk"
      responses:
        202:
          description: "Request accepted"
        400:
          $ref: '#/responses/BadRequestError'
        500:
          $ref: '#/responses/InternalError'
  /groups:
    get:
      tags:
        - Groups
      summary: "List groups"
      description: "List all the groups in the user pool"
      security:
        - Authorization: []
      produces:
        - "application/json"
      parameters:
        - in: query
          name: sort
          type: string
          required: false
          default: created
          enum:
            - created
            - name
            - name:asc
            - name:desc
      responses:
        200:
          description: "The list of groups"
          schema:
            $ref: '#/definitions/GroupList'
        400:
          $ref: '#/responses/BadRequestError'
        401:
          $ref: '#/responses/UnauthorizedError'
        500:
          $ref: '#/responses/InternalError'
    post:
      tags:
        - Groups
      summary: "Create a new group"
      description: "Creates a new group in Cognito user pool"
      security:
        - Authorization: []
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: body
          name: "Group"
          description: "The details of the group being created"
          required: true
          schema:
            required: 
              - "name"
              - "precedence"
            type: object
            properties:
              name:
                type: string
                example: "Th&is is a $£test group!~"
              precedence:
                type: integer
                example: 33
      responses:
        201:
          description: "The group has been successfully created"
          schema:
            $ref: '#/definitions/NewGroup'
        400:
          $ref: '#/responses/BadRequestError'
        401:
          $ref: '#/responses/UnauthorizedError'
        500:
          $ref: '#/responses/InternalError'
  /groups/{id}:
    get:
      tags:
        - Groups
      summary: "Get a group"
      description: "Get a group"
      security:
        - Authorization: []
      produces:
        - "application/json"
      parameters:
        - in: path
          name: id
          type: string
          required: true
          description: the group's ID
      responses:
        200:
          description: "The group details"
          schema:
            $ref: '#/definitions/Group'
        400:
          $ref: '#/responses/BadRequestError'
        401:
          $ref: '#/responses/UnauthorizedError'
        500:
          $ref: '#/responses/InternalError'
    put:
      tags:
        - Groups
      summary: "Update an existing group"
      description: "Update an existing group in Cognito user pool"
      security:
        - Authorization: []
      consumes:
        - application/json
      produces:
        - "application/json"
      parameters:
        - in: path
          name: id
          type: string
          required: true
          description: the group's ID
        - in: body
          name: "Group"
          description: "The updated details for the group"
          required: true
          schema:
            required: ["name"]
            type: object
            properties:
              name:
                type: string
                example: "Th&is is a $£test group!~"
              precedence:
                type: integer
                example: 33
      responses:
        200:
          description: "The group has been successfully updated"
          schema:
            $ref: '#/definitions/NewGroup'
        400:
          $ref: '#/responses/BadRequestError'
        401:
          $ref: '#/responses/UnauthorizedError'
        404:
          description: "Group resource to be updated cannot be found"
          schema:
            $ref: '#/definitions/ErrorList'
        500:
          $ref: '#/responses/InternalError'
    delete:
      tags:
        - Groups
      summary: "Delete a group"
      description: "Delete a group"
      security:
        - Authorization: []
      produces:
        - "application/json"
      parameters:
        - in: path
          name: id
          type: string
          required: true
          description: the group's ID
      responses:
        204:
          description: "Deleted group"
        401:
          $ref: '#/responses/UnauthorizedError'
        404:
          description: "Group resource to be deleted cannot be found"
          schema:
            $ref: '#/definitions/ErrorList'
        500:
          $ref: '#/responses/InternalError'
  /groups/{id}/members:
    get:
      tags:
        - Groups
      summary: "Get a list of users in a group"
      description: "Returns a list of users in a given group in Cognito"
      security:
        - Authorization: []
      produces:
        - "application/json"
      parameters:
        - in: path
          name: id
          type: string
          required: true
          description: the group's ID
        - in: query
          name: sort
          description: The sort order of the returned set of users
          type: string
          required: false
          default: created
          enum:
            - created
            - forename:asc
            - forename:desc
      responses:
        200:
          description: "List of users in the group"
          schema:
            $ref: '#/definitions/UserList'
        401:
          $ref: '#/responses/UnauthorizedError'
        404:
          description: "Group resource cannot be found"
          schema:
            $ref: '#/definitions/ErrorList'
        500:
          $ref: '#/responses/InternalError'
    post:
      tags:
        - Groups
      summary: "Add user to group"
      description: "Adds a user to an existing group in Cognito"
      security:
        - Authorization: []
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: path
          name: id
          type: string
          required: true
          description: the group's ID
        - in: body
          name: "User ID"
          description: "The ID of the user being added to the group"
          schema:
            required: 
              - "user_id"
            type: object
            properties:
              user_id:
                type: string
      responses:
        200:
          description: "User added to group"
          schema:
            $ref: '#/definitions/Group'
        400:
          $ref: '#/responses/BadRequestError'
        401:
          $ref: '#/responses/UnauthorizedError'
        500:
          $ref: '#/responses/InternalError'
    put:
      tags:
        - Groups
      summary: "Update groups users"
      description: "Update groups users"
      security:
        - Authorization: []
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: path
          name: id
          type: string
          required: true
          description: the group's ID
        - in: body
          name: "List of User ids"
          description: "The list of user ids being added to the group"
          required: true
          schema:
            required: 
              - "user_id"
            type: object
            properties:
              user_id:
                type: string
      responses:
        200:
          description: "List of users in updated group"
          schema:
            $ref: '#/definitions/UserList'
        400:
          $ref: '#/responses/BadRequestError'
        401:
          $ref: '#/responses/UnauthorizedError'
        500:
          $ref: '#/responses/InternalError'
  /groups/{id}/members/{user_id}:
    delete:
      tags:
        - Groups
      summary: "Remove user from group"
      description: "Removes a user from an existing group in Cognito"
      security:
        - Authorization: []
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: path
          name: id
          type: string
          required: true
          description: the group's ID
        - in: path
          name: user_id
          type: string
          required: true
          description: the id of the user being removed from the group
      responses:
        200:
          description: "User removed from group"
          schema:
            $ref: '#/definitions/Group'
        400:
          $ref: '#/responses/BadRequestError'
        401:
          $ref: '#/responses/UnauthorizedError'
        500:
          $ref: '#/responses/InternalError'
  /groups-report:
    get:
      tags:
        - Groups
      summary: "List groups and the membership of the groups"
      description: |
        The list of group memebership with the following fields:
          * group description
          * group member user email
        Format is JSON by default or csv format if Request Header Accept 'text/csv' is specified.
        
        Included on report: groups acting as a role (i.e. publishers, admin)
        Excluded from Report: groups that are empty of users
      security:
        - Authorization: []
      consumes:
        - "application/json"
      produces:
        - "application/json"
        - "text/csv"
      parameters:
        - in: header
          name: Accept
          type: string
          enum:
            - "application/json"
            - "text/csv"
          required: false
          description: "Whether a JSON or CSV report is requested"
      responses:
        200:
          description: The list of groups and members
          schema:
            $ref: '#/definitions/GroupUsersList'
          examples:
            application/json:
              [
                {
                  "group": "group description",
                  "user": "user.email@emaildomain"
                }
              ]
            text/csv: |-
              group,user 
              group description,user.email@emaildomain
        401:
          $ref: '#/responses/UnauthorizedError'
        500:
          $ref: '#/responses/InternalError'
  /jwt-keys:
    get:
      tags:
        - JWKS
      summary: "JSON Web Key Set"
      description: "Returns AWS Cognito User Pool's JWT Key IDs and RSA Public Signing Keys"
      security: []
      produces:
        - "application/json"
      responses:
        200:
          description: "Key set retrieved, processed and returned in response body"
          schema:
            $ref: '#/definitions/JWKSResponse'
        404:
          description: "Key set not found or error processing it"
          schema:
            $ref: '#/definitions/ErrorList'
        500:
          $ref: '#/responses/InternalError'

responses:
  InternalError:
    description: "Failed to process the request due to an internal error"
    schema:
      $ref: '#/definitions/ErrorList'
  BadRequestError:
    description: "Request rejected due to invalid parameters supplied"
    schema:
      $ref: '#/definitions/ErrorList'
  UnauthorizedError:
    description: Authentication information is missing or invalid

definitions:
  ExpirationTime:
    type: object
    properties:
      expirationTime:
        type: string
        description: "Expiration Time, UTC ISO 8601"
        example: "YYYY-MM-DD hh:mm:ssZ"
  SignInExpirationTime:
    type: object
    properties:
      expirationTime:
        type: string
        description: "Expiration Time, UTC ISO 8601"
        example: "YYYY-MM-DD hh:mm:ssZ"
      refreshTokenExpirationTime:
        type: string
        description: "Expiration Time, UTC ISO 8601"
        example: "YYYY-MM-DD hh:mm:ssZ"
  PasswordResetExpirationTime:
    type: object
    properties:
      expirationTime:
        type: string
        description: "Expiration Time, UTC ISO 8601"
        example: "YYYY-MM-DD hh:mm:ssZ"
      refreshTokenExpirationTime:
        type: string
        description: "Refresh Token Expiration Time, UTC ISO 8601"
        example: "YYYY-MM-DD hh:mm:ssZ"
  NewGroup:
    description: "The new group details for the response body"
    type: object
    properties:
      id:
        description: "The unique ID of the group"
        type: string
        example: "123-abc-456-def-789-ghi-0"
      name:
        description: "The human readable name of the group"
        type: string
        example: "thisisatestgroup"
      precedence:
        description: "The precedence of the group"
        type: integer
        example: 33
  Group:
    description: "A group in the user pool"
    type: object
    properties:
      id:
        description: "The group ID"
        type: string
      name:
        description: "The group name"
        type: string
      precedence:
        description: "The priority of the group"
        type: integer
      created:
        description: "The date the group was created"
        type: string
        format: date-time
        example: "YYYY-MM-DD hh:mm:ssZ"
      last_modified_date:
        type: string
        format: date-time
        example: "YYYY-MM-DD hh:mm:ssZ"
      role_arn:
        type: string
      user_pool_id:
        type: string
  GroupList:
    description: "A list of groups"
    type: object
    properties:
      groups:
        type: array
        items:
          $ref: '#/definitions/Group'
      count:
        type: integer
  GroupUsersList:
    description: A list of group descriptions and members emails
    type: array
    items:
      $ref: '#/definitions/GroupUser'
  GroupUser:
    description: Group description and user email
    type: object
    properties:
      group:
        type: string
        description: The group description
      user:
        type: string
        description: The user email
  UserList:
    description: "A list of users"
    type: object
    properties:
      users:
        type: array
        items:
          $ref: '#/definitions/User'
      count:
        type: integer
  User:
    description: "A user in cognito"
    type: object
    properties:
      id:
        description: "The users id"
        type: string
      forename:
        description: "The users forename"
        type: string
      surname:
        description: "The users surname"
        type: string
      email:
        description: "The users email address"
        type: string
      groups:
        description: "The groups the user belongs to"
        type: array
        items:
          description: "The groups name"
          type: string
      active:
        description: "Whether or not the user is active"
        type: boolean
      status_notes:
        description: "Notes about the updates made to the user"
        type: string
        example: "User has been suspended"
      status:
        description: "The current status of the user"
        type: string
        enum: 
          - "UNCONFIRMED"
          - "CONFIRMED"
          - "ARCHIVED"
          - "COMPROMISED"
          - "UNKNOWN"
          - "RESET_REQUIRED"
          - "FORCE_CHANGE_PASSWORD"
        example: "CONFIRMED"
  JWKSResponse:
    description: :-
      The keys in this object are dynamically generated and so the below should be taken
      as an example and not definitive.
    properties:
      2a8vXmIK67ZZ3hFZ=:
        type: string
        example: "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApU1DqxJalEmlznkrM+U4aSBMw9u5axcIqNeUq8+ZHo98uKy8Xy5zCOXfWx6KafOPJhbOZInFaSh9UMaluSSw11l/PR4KrGBFzJODQ+RMq6bHW6FlwwHSkMTSfQ0hwzO7y91BiZFmJnaUECf52H3QBApGT4TT060ri5zt1ygpliRwjLLlHW1XX0epzZH3ogrikn4i65e8w6uUcsGBhQvQQqiHvEpcgCQAB"
      GRBevIroJzPBvaGa=:
        type: string
        example: "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtvDfudfY9n+8sFJmHGFfgbKqKf8iiEcbvRXNMEi9qd2NGAekhdNJKdeW3sMSwR+sb4Ly6IypowCE2eueYk/GatzYyyolWny/Krdp0EWPT/PnK8Iq1FTIuHxFb08B8iLnH/2nKqgOjVvwEU4eSBh0YHKti2v77a+a4bnx6aOC2YkF2AyIRmbXAHaq4Js9u33X8gGMXZcVsxcSpG8Py/NJ3s+PLKebQFQAB"
  ErrorList:
    description: "A list of any errors"
    type: object
    properties:
      errors:
        type: array
        items:
          $ref: '#/definitions/Error'
  Error:
    description: "An individual error details"
    type: object
    properties:
      code:
        type: string
        description: "Code representing the type of error that occurred"
        enum:
          - "InvalidUserId"
          - "InvalidGroupID"
          - "InvalidForename"
          - "InvalidSurname"
          - "InvalidStatusNotes"
          - "InvalidEmail"
          - "InvalidToken"
          - "InternalServerError"
          - "NotFound"
          - "UserNotFound"
          - "GroupExists"
          - "GroupNotFound"
          - "DeliveryFailure"
          - "InvalidCode"
          - "ExpiredCode"
          - "InvalidField"
          - "InvalidPassword"
          - "LimitExceeded"
          - "NotAuthorised"
          - "PasswordResetRequired"
          - "TooManyFailedAttempts"
          - "TooManyRequests"
          - "UserNotConfirmed"
          - "UsernameExists"
          - "MissingConfig"
          - "UnknownRequestType"
          - "BodyCloseError"
          - "InvalidGroupName"
          - "InvalidGroupPrecedence"
          - "InvalidFilterQuery"
          - "JWKSParseError"
      description:
        type: string
        description: "Description of the error"
securityDefinitions:
  Authorization:
    name: Authorization
    description: "Access token used by Auth service in a Bearer format"
    in: header
    type: apiKey