# # Copyright (C) 2015 The Gravitee team (http://gravitee.io) # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # swagger: '2.0' info: description: >- Gravitee.io - Access Management - Self-service Account Management API. Defines Self Account Management Endpoints exposed by AM server. Self Account Management endpoints are OAuth 2.0 secured and can be accessed with the 'sub' claim of the current user. version: 4.0.x title: Gravitee.io - Access Management - Self-service Account Management API contact: email: contact@graviteesource.com license: name: Apache 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0.html' host: auth.gravitee.io basePath: /{domain}/account schemes: - https paths: /api/changePassword: get: tags: - Self Account summary: Initiates dialog to change user password responses: '302': description: redirection to forgotten password '401': description: Invalid Token post: tags: - Self Account summary: Update directly the user password consumes: - application/json parameters: - in: body name: password required: true description: The new password value. - in: body name: oldPassword required: false description: The old password value. This parameter maybe required based on the security domain configuration. responses: '204': description: Password updated '400': description: Password Invalid '401': description: Invalid Token '403': description: Action forbidden /api/profile: get: tags: - Self Account summary: Gets current user's profile description: Gets a profile for the current user produces: - application/json responses: '200': description: A JSON object that represents a user profile schema: $ref: '#/definitions/UserProfile' '401': description: Invalid Token put: tags: - Self Account summary: Updates current user's profile produces: - application/json parameters: - in: body name: User update description: New user information for update schema: $ref: '#/definitions/UpdateUser' responses: '200': description: A JSON object that represents the status of the request. schema: $ref: '#/definitions/StatusResponse' '401': description: Invalid Token /api/profile/username: patch: tags: - Self Account summary: Updates username for current user's profile produces: - application/json parameters: - in: body name: Username update description: New username schema: $ref: '#/definitions/UpdateUsername' responses: '200': description: A JSON object that represents the status of the request. schema: $ref: '#/definitions/StatusResponse' '401': description: Invalid Token /api/activity: get: tags: - Self Account summary: Get current user's recent activity produces: - application/json responses: '200': description: A JSON object that represents a user's recent activity. schema: $ref: '#/definitions/UserActivityPage' '401': description: Invalid Token /api/factors: get: tags: - Self Account summary: Get enrolled factors for the current user produces: - application/json responses: '200': description: The enrolled factors schema: $ref: '#/definitions/EnrolledFactors' '401': description: Invalid Token post: tags: - Self Account summary: Enroll a factor for the current user consumes: - application/json produces: - application/json parameters: - in: body name: factor description: The factor to enroll. schema: $ref: '#/definitions/Enrollment' responses: '201': description: A JSON object that represents the factor enrolled schema: $ref: '#/definitions/EnrolledFactor' '401': description: Invalid Token /api/factors/catalog: get: tags: - Self Account summary: List security domain factors produces: - application/json responses: '200': description: The security domain factors schema: $ref: '#/definitions/FactorsToEnroll' '401': description: Invalid Token /api/factors/{factorId}: get: tags: - Self Account summary: Get enrolled factor detail for the current user produces: - application/json parameters: - in: path name: factorId type: string required: true description: Unique identifier for the factor responses: '200': description: Enrolled factor detail schema: $ref: '#/definitions/EnrolledFactor' '401': description: Invalid Token put: tags: - Self Account summary: Update an enrolled factor for the current user consumes: - application/json produces: - application/json parameters: - in: path name: factorId type: string required: true description: Unique identifier for the factor - in: body name: factor description: The factor to update. schema: $ref: '#/definitions/EnrolledFactorToUpdate' responses: '200': description: Enrolled factor detail schema: $ref: '#/definitions/EnrolledFactor' '401': description: Invalid Token delete: tags: - Self Account summary: Remove an enrolled factor for the current user parameters: - in: path name: factorId type: string required: true description: Unique identifier for the factor responses: '204': description: Factor is deleted '401': description: Invalid Token /api/factors/{factorId}/qr: get: tags: - Self Account summary: Get the QR code that encodes the activation code produces: - application/json parameters: - in: path name: factorId type: string required: true description: Unique identifier for the factor responses: '200': description: The QR code is base64 format schema: type: object properties: qrCode: type: string description: base64 QR code format. '401': description: Invalid Token /api/factors/{factorId}/verify: post: tags: - Self Account summary: Verify a factor consumes: - application/json produces: - application/json parameters: - in: path name: factorId type: string required: true description: Unique identifier for the factor - in: body name: security description: Security information to activate a factor schema: $ref: '#/definitions/EnrolledFactorSecurity' responses: '200': description: Enrolled factor detail schema: $ref: '#/definitions/EnrolledFactor' '400': description: Invalid request '401': description: Invalid Token '403': description: Invalid code '404': description: Unknown factor /api/factors/{factorId}/sendChallenge: post: tags: - Self Account summary: Issue a factor challenge consumes: - application/json produces: - application/json parameters: - in: path name: factorId type: string required: true description: Unique identifier for the factor responses: '200': description: Enrolled factor detail schema: $ref: '#/definitions/EnrolledFactor' '400': description: Invalid factor '401': description: Invalid Token '404': description: Unknown factor '500': description: Send challenge exception /api/auth/recovery_code: get: tags: - Self Account summary: Get enrolled recovery codesfor the current user produces: - application/json responses: '200': description: Enrolled recovery codes schema: $ref: '#/definitions/EnrolledRecoveryCodes' '401': description: Invalid Token post: tags: - Self Account summary: Generate recovery codesfor the current user produces: - application/json responses: '200': description: Enrolled recovery codes schema: $ref: '#/definitions/EnrolledRecoveryCodes' '401': description: Invalid Token delete: tags: - Self Account summary: Delete recovery codes for the current user responses: '204': description: Recovery codes deleted '401': description: Invalid Token /api/webauthn/credentials: get: tags: - Self Account summary: Get enrolled WebAuthn credential detail for the current user produces: - application/json responses: '200': description: The enrolled WebAuthn credentials schema: $ref: '#/definitions/EnrolledWebAuthnCredentials' '401': description: Invalid Token /api/webauthn/credentials/{credentialId}: get: tags: - Self Account summary: Get enrolled WebAuthn credentials for the current user produces: - application/json parameters: - in: path name: credentialId type: string required: true description: Unique identifier for the WebAuthn credential responses: '200': description: The enrolled WebAuthn credentials schema: $ref: '#/definitions/EnrolledWebAuthnCredential' '401': description: Invalid Token put: tags: - Self Account summary: Update enrolled WebAuthn credentials for the current user consumes: - application/json produces: - application/json parameters: - in: path name: credentialId type: string required: true description: Unique identifier for the WebAuthn credential - in: body name: deviceName description: Device name of the WebAuthn credential schema: $ref: '#/definitions/EnrolledWebAuthnCredentialToUpdate' responses: '200': description: The enrolled WebAuthn credentials has been updated schema: $ref: '#/definitions/EnrolledWebAuthnCredential' '400': description: Bad Request '401': description: Invalid Token delete: tags: - Self Account summary: Delete enrolled WebAuthn credentials for the current user produces: - application/json parameters: - in: path name: credentialId type: string required: true description: Unique identifier for the WebAuthn credential responses: '204': description: The enrolled WebAuthn credentials has been deleted '401': description: Invalid Token /api/consent: get: tags: - Self Account summary: Get list of consent for the current user produces: - application/json responses: '200': description: The user consent list schema: $ref: '#/definitions/UserConsentList' '401': description: Invalid Token /api/consent/{consentId}: get: tags: - Self Account summary: Get consent detail for the current user produces: - application/json parameters: - in: path name: consentId type: string required: true description: Unique identifier for the consent responses: '200': description: The enrolled WebAuthn credentials schema: $ref: '#/definitions/UserConsent' '401': description: Invalid Token delete: tags: - Self Account summary: Remove a consent for the current user parameters: - in: path name: consentId type: string required: true description: Unique identifier for the consent responses: '204': description: Consent is deleted '401': description: Invalid Token securityDefinitions: bearerAuth: type: oauth2 flow: application tokenUrl: https://auth.gravitee.io/{domain}/oauth/token definitions: UserProfile: type: object properties: id: type: string description: User's technical id. externalId: type: string description: External IDP technical id. username: type: string description: User's username. displayName: type: string description: User's display name. roles: type: object properties: schemas: type: array description: User's list of applied roles.. items: $ref: '#/definitions/UserRole' accountNonExpired: type: boolean description: Boolean description of user's expired position. accountNonLocked: type: boolean description: Boolean description of user's locked position. credentialsNonExpired: type: boolean description: Boolean description of user's credential expired position. enabled: type: boolean description: Boolean description of user's enabled position. internal: type: boolean description: Boolean description of user's internal position. preRegistration: type: boolean description: Boolean description of user's preregistration position. registrationCompleted: type: boolean description: Boolean description of user's registration completed position. referenceType: type: string description: User's reference type. referenceId: type: string description: Reference technical id. source: type: string description: Source technical uuid. client: type: string description: Client technical uuid. loginsCount: type: integer description: Total count of all occasions of specific user logins. additionalInformation: type: object additionalProperties: true description: Hashmap/Dictionary of additional user information. loggedAt: type: integer description: Epoch timestamp of last log in of user. createdAt: type: integer description: Epoch timestamp of creation of user. updatedAt: type: integer description: Epoch timestamp of last update of user. inactive: type: boolean description: Boolean description of user's inactive position. UpdateUsername: type: object properties: username: type: string description: New username to apply on the user profile. UpdateUser: type: object properties: name: type: string description: Name. given_name: type: string description: Given Name. family_name: type: string description: Family Name. middle_name: type: string description: Middle Name. nickname: type: string description: Nickname. profile: type: string description: URL link to profile. picture: type: string description: URL link to picture. website: type: string description: URL link to website. email: type: string description: User email address. gender: type: string description: Gender. birthdate: type: string description: Birthdate in yyyy-mm-dd format. zoneinfo: type: string description: User zone info. locale: type: string description: User locale. phone_number: type: string description: user phone number. address: type: object additionalProperties: true description: Hashmap/Dictionary of additional user address information. UserRole: type: object additionalProperties: true description: Hashmap/Dictionary of additional user role information. StatusResponse: type: object properties: status: type: string description: status either OK or KO. UserActivityPage: type: object properties: data: type: object properties: schemas: type: array description: User's list of applied roles.. items: $ref: '#/definitions/UserActivity' totalCount: type: integer description: Total count of all auditable activies for current user. currentPage: type: integer description: Current page of activities paging within the data list. UserActivity: type: object properties: id: type: string description: Activities's technical id. transactionId: type: string description: Transaction's technical id. type: type: string description: Type of activity. referenceType: type: string description: Type of reference. accessPoint: type: object description: Description of access point. actor: type: object description: Description of actor in activity. outcome: type: object description: Overall outcome of activity. FactorsToEnroll: type: object properties: schemas: type: array description: Avaibable factors to enroll items: $ref: '#/definitions/FactorToEnroll' FactorToEnroll: type: object properties: id: type: string description: Factor technical id name: type: string description: Factor name factorType: type: string description: Factor type resource: type: string description: Factor resource if any EnrolledFactors: type: object properties: schemas: type: array description: Enrolled factors for the current user items: $ref: '#/definitions/EnrolledFactor' EnrolledFactor: type: object properties: id: type: string description: Factor technical id name: type: string description: Factor name factorType: type: string description: Factor type resource: type: string description: Factor resource if any createdAt: type: number description: Factor enrollment date status: type: string description: Factor enrollment state enrollment: type: object description: Enrollment information to activate the factor (only available after create action) properties: sharedSecret: type: string description: Shared secret (for TOTP factor) timeStep: type: string description: Time step (for TOTP factor) codeLength: type: string description: Digit code length (for TOTP factor) Enrollment: type: object properties: factorId: type: string description: Factor technical ID to enroll account: type: object description: Account information to enroll the factor properties: phoneNumber: type: string description: User phone number (if factor type is SMS or CALL) extensionPhoneNumber: type: string description: User phone number extension (if factor type is SMS or CALL). The digits to send after a phone call is answered. email: type: string description: User email (if factor type is EMAIL) EnrolledFactorSecurity: type: object description: Security information to activate a factor properties: code: type: string description: TOTP code or SMS/EMAIL MFA code EnrolledWebAuthnCredentials: type: object properties: schemas: type: array description: Enrolled WebAuthn credentials for the current user items: $ref: '#/definitions/EnrolledWebAuthnCredential' EnrolledWebAuthnCredential: type: object properties: id: type: string description: WebAuthn credential technical id credentialId: type: string description: WebAuthn credential id publicKey: type: string description: WebAuthn credential public key aaguid: type: string description: WebAuthn credential AAGUID attestationStatementFormat: type: string description: WebAuthn credential attestation statement format attestationStatement: type: string description: WebAuthn credential attestation statement ipAddress: type: string description: IP address used to register the credential userAgent: type: string description: User-agent used to register the credential createdAt: type: number description: WebAuthn credential creation date updatedAt: type: number description: WebAuthn credential update date accessedAt: type: number description: WebAuthn credential last use date EnrolledWebAuthnCredentialToUpdate: type: object properties: deviceName: type: string description: WebAuthn credential device name EnrolledFactorToUpdate: type: object properties: primary: type: boolean description: Primary state of the enrolled factor EnrolledRecoveryCodes: type: array items: type: string UserConsentList: type: object properties: schemas: type: array description: List of consent for the current user items: $ref: '#/definitions/UserConsent' UserConsent: type: object properties: id: type: string description: Consent technical id transactionId: type: string description: Consent transaction id domain: type: string description: Security domain used during consent creation clientId: type: string description: Client ID used during consent creation userId: type: string description: User technical ID of the consent scope: type: string description: Scope of the consent status: type: string enum: [APPROVED, DENIED] description: Status of the consent createdAt: type: number description: Consent creation date updatedAt: type: number description: Consent update date expiresAt: type: number description: Consent expiration date