openapi: 3.0.1 info: title: Authentication Service REST APIs description: Authentication Service Internal REST APIs version: '1' servers: - url: 'https://api.plumery.com' description: Live Server paths: /internal/v1/auth/ciba/backchannel-auth: post: tags: - CIBA summary: CIBA Backchannel Authentication operationId: CIBA Backchannel Authentication description: | This endpoint accepts the same parameters as the standard CIBA backchannel authentication API and returns **CIBA-compliant** success and error responses (not wrapped into Plumery error structures). Either login_hint, id_token_hint or login_hint_token must be provided. Examples for App authentication error code: `invalid_request`, error_description: - "invalid user": user does not exist - "missing valid device": user has no registered devices - "missing valid device authentication": user device has no authentication certificates The login_hint parameter accepts multiple formats in order to identify the user: - the plain username without any prefix (e.g. `login_hint = "john.doe"`) - personalId format: personalId:{countryCode}:{personalId} (e.g. `login_hint = "personalId:LT:1234567890"`) - username format: username:{username} (e.g. `login_hint = "username:john.doe"`) The `phone_number` is mandatory if `acr_values = "mobile-id"`. The `phone_number` must match the phone number of the user corresponding to the `login_hint`. If the field is provided optionally for another `acr_values`, the previous validation will still be performed. The `personal_id` and `country` are mandatory if `acr_values = "smart-id"`. They must match the `personal_id` and `country` of the user corresponding to the `login_hint`. If the fields are provided optionally for another `acr_values`, the previous validations will still be performed. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object description: "Request body" required: - scope properties: scope: type: string description: Space-separated list of requested scopes. Must include openid. login_hint: type: string description: Hint about the login identifier of the user. id_token_hint: type: string description: Previously issued ID Token used as a hint about the user. login_hint_token: type: string description: Token that contains information identifying the user. acr_values: type: string description: Requested Authentication Context Class Reference values. binding_message: type: string description: | Human-readable message displayed to the user on the authenticating device. requested_expiry: type: integer format: int32 description: Requested expiry time for the auth_req_id in seconds. personal_id: type: string description: Custom field with user's personal identifier. Used in case of eId provider is used for authentication. phone_number: type: string description: Custom field with user's phone number. Used in case of eId provider is used for authentication country: type: string description: Custom field with the user's country code. Used in case of eId provider is used for authentication authentication_code_base_64: type: string description: Custom base64 encoded authentication code. Used in case of eId provider is used for authentication. Should be specifically passed depending on eId provider. responses: '200': description: CIBA backchannel authentication request accepted. content: application/json: schema: $ref: '#/components/schemas/CibaBackchannelAuthResponse' '400': description: CIBA-compliant error for invalid or malformed request. content: application/json: schema: $ref: '#/components/schemas/CibaErrorResponse' '401': description: CIBA-compliant error for invalid or unauthorized client. content: application/json: schema: $ref: '#/components/schemas/CibaErrorResponse' '500': description: CIBA-compliant server error. content: application/json: schema: $ref: '#/components/schemas/CibaErrorResponse' default: description: Unexpected CIBA-compliant error. content: application/json: schema: $ref: '#/components/schemas/CibaErrorResponse' x-internal: true /internal/v1/auth/ciba/token: post: tags: - CIBA summary: CIBA Token Endpoint operationId: CIBA Token Endpoint description: | Returns **CIBA-compliant** token or error responses as per OAuth 2.0 and CIBA specifications, without wrapping into Plumery-specific error structures. Examples for App authentication error code, error_description: - `access_denied`, "not authorized": Pending authentication was rejected by the user or the user didn't approve the authentication request.' - `authorization_pending`, "The authorization request is still pending as the end-user hasn't yet been authenticated.": Pending authentication was not confirmed by the user yet. requestBody: required: true description: "Request body" content: application/x-www-form-urlencoded: schema: type: object required: - grant_type - auth_req_id properties: grant_type: type: string description: OAuth 2.0 grant type. For CIBA this is typically `urn:openid:params:grant-type:ciba`. example: urn:openid:params:grant-type:ciba auth_req_id: type: string description: Authentication request identifier returned by the backchannel-auth endpoint. responses: '200': description: Token successfully issued for completed CIBA authentication. content: application/json: schema: $ref: '#/components/schemas/CibaTokenSuccessResponse' '400': description: CIBA-compliant error for invalid request, expired or pending auth_req_id. content: application/json: schema: $ref: '#/components/schemas/CibaErrorResponse' '401': description: CIBA-compliant error for invalid or unauthorized client. content: application/json: schema: $ref: '#/components/schemas/CibaErrorResponse' '500': description: CIBA-compliant server error. content: application/json: schema: $ref: '#/components/schemas/CibaErrorResponse' default: description: Unexpected CIBA-compliant error. content: application/json: schema: $ref: '#/components/schemas/CibaErrorResponse' x-internal: true components: schemas: PendingAuthenticationRequest: type: object description: Request for initiating a pending authentication flow for a user. required: - flowName properties: flowName: type: string description: Name of the authentication flow to execute. example: device-binding-flow deviceId: type: string description: Identifier of the device initiating the authentication. example: 8c4baf1b-0dfd-4ad9-bf2c-4b0b2819e0e7 PendingAuthenticationResponse: type: object description: Single pending authentication entry for a given user. properties: id: type: string description: Unique identifier of the pending authentication request. example: 1b2a754f-4e6a-4bf8-9f5a-9d84a52b0a11 username: type: string description: Username for whom the authentication is pending. example: john.doe bindingMessage: type: string nullable: true description: Human readable message that is displayed on the authenticating device. example: Approve login for MyBank web session createdAt: type: string format: date-time description: Time when this pending authentication was created. example: 2025-01-01T10:15:30Z PendingAuthenticationsResponse: type: object description: List of pending authentications for a given user. properties: pendingAuthentications: type: array items: $ref: '#/components/schemas/PendingAuthenticationResponse' CibaBackchannelAuthResponse: type: object description: > Successful CIBA backchannel authentication response as defined by OpenID Connect CIBA. required: - auth_req_id - expires_in properties: auth_req_id: type: string description: Authentication request identifier used later on the token endpoint. example: 9b4b26c0-2c7b-4ccb-b9a8-1f0a496f3a51 expires_in: type: integer format: int32 description: Lifetime in seconds of the auth_req_id. example: 120 interval: type: integer format: int32 description: > Minimum amount of time in seconds that the client must wait between polling requests to the token endpoint. example: 5 CibaTokenSuccessResponse: type: object description: > Successful token response issued after a completed CIBA authentication request. required: - access_token - expires_in - token_type properties: access_token: type: string description: Access token issued by the authorization server. expires_in: type: integer format: int32 description: Lifetime in seconds of the access token. example: 3600 token_type: type: string description: Type of the token issued. example: Bearer refresh_token: type: string description: Refresh token which can be used to obtain new access tokens. id_token: type: string description: ID Token containing claims about the authenticated end-user. scope: type: string description: Space-separated list of scopes associated with the issued tokens. authentication_method: type: string description: Authentication method performed by the user. enum: - smart-id - mobile-id - app-passcode - app-biometrics CibaErrorResponse: type: object description: > Error response for CIBA endpoints, following OAuth 2.0 and OpenID Connect error format. required: - error properties: error: type: string description: Error code. enum: - invalid_request - invalid_client - invalid_grant - unauthorized_client - access_denied - invalid_scope - authorization_pending - slow_down - expired_token - server_error - temporarily_unavailable error_description: type: string description: Human-readable ASCII text providing additional information about the error. error_uri: type: string format: uri description: URI identifying a human-readable web page with information about the error.