--- openapi: 3.0.3 info: title: PACE User Management description: | The PACE User API is responsible for user related actions. # Handling Terms of Service PACE services often require the acceptance of *Terms of Service* to execute API actions. The terms are required for legal reasons. Some of the API surface may not require the acceptance of terms. Usually, the terms need to be accepted before doing manipulations like `DELETE`, `PUT`, `POST` and similar. If a service requires a user to accept the terms of service a `451 Unavailable For Legal Reasons` status code will be returned together with a `Location` header that indicates the terms that need to be accepted. The URL points to the [GetTerms](#operation/GetTerms) and can then be followed by the [AcceptTerms](#operation/AcceptTerms). The terms can be viewed and accepted with a regular browser. A simple way to assure that the *terms of service* are accepted, before the user does any action is, to call the [CheckTerms](#operation/CheckTerms) API before the application, together with a `redirectUri` to the next step of the application process. termsOfService: https://legal.pace.cloud/ contact: name: PACE Developer Support url: https://developer.pace.cloud email: api-access@pace.car version: 2024-1 servers: - url: https://api.pace.cloud/user/2024-1 description: Preview paths: "/terms/check": get: tags: - Terms operationId: CheckTerms summary: Checks acceptance of the terms of service for a user and a service. description: | Fetches the latest terms for the given UUID. In order to identify the user any oauth2 token must be passed. security: - OAuth2: [] - OIDC: [] parameters: - in: query required: true name: filter[serviceName] description: The name of the service schema: type: string example: PACE Connected Fueling enum: - PACE ID - PACE Connected Fueling - PACE Pay - PACE Community - PACE Car App - PACE Drive App - in: query name: redirectUri schema: type: string description: 'An optional URI to redirect to in case terms of service are accepted. This parameter only has effect to the `text/html` version of the terms as specified in [GetTerms](#operation/GetTerms). ' example: https://app.example.com?terms-accepted=true responses: '204': description: Terms found and accepted by the user '302': description: Terms found but user didn't accept latest terms version headers: Location: description: Location of terms to accept schema: type: string format: url '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" '501': "$ref": "#/components/responses/InternalServerError" "/terms/latest": get: tags: - Terms operationId: LatestTerms summary: Returns the latest terms of service by serviceName description: 'Fetches the latest terms for the given `serviceName`. ' parameters: - in: query required: true name: filter[serviceName] description: The name of the service schema: type: string example: PACE Fueling responses: '200': description: Terms found headers: Content-Language: schema: type: string description: Language of the localized response properties. Is not necessarily one of the values provided by the Accept-Language request header. example: en-GB content: application/vnd.api+json: schema: type: object properties: data: "$ref": "#/components/schemas/Terms" '404': "$ref": "#/components/responses/NotFound" '501': "$ref": "#/components/responses/InternalServerError" "/terms/{termsId}": get: tags: - Terms operationId: GetTerms summary: Returns the latest terms of service by UUID description: 'Fetches the latest terms for the given UUID. ' parameters: - in: path name: termsId schema: type: string format: uuid description: The ID of the terms. example: 2a1319c3-c136-495d-b59a-47b3246d08af - in: query name: redirectUri schema: type: string description: 'An optional URI to redirect to in case terms of service are accepted. This parameter only has effect to the `text/html` version of the terms. ' example: https://app.example.com?terms-accepted=true - in: header name: Accept-Language schema: type: string description: Provides the preferred language for the user terms example: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5 responses: '200': description: Terms found headers: Content-Language: schema: type: string description: Language of the localized response properties. Is not necessarily one of the values provided by the Accept-Language request header. example: en-GB content: application/vnd.api+json: schema: type: object properties: data: "$ref": "#/components/schemas/Terms" text/html: schema: type: string description: A browser friendly version of the terms of service including an accept button example: "..." '302': description: Terms found and user accepted the last version headers: Location: description: 'Directs the browser to go to the passed `redirectUri`, only if no `Accept: application/vnd.api+json` is send' schema: type: string format: url '404': "$ref": "#/components/responses/NotFound" '501': "$ref": "#/components/responses/InternalServerError" "/terms/{termsId}/accept": post: tags: - Terms operationId: AcceptTerms security: - OAuth2: - user:terms:accept - OIDC: - user:terms:accept summary: Accepts the terms presented under the UUID description: | Accepts the terms using the user that is linked in the token. This endpoint must only be called as a reaction of direct user consent with the terms of service. parameters: - in: path name: termsId schema: type: string format: uuid description: The ID of the terms. example: 2a1319c3-c136-495d-b59a-47b3246d08af responses: '204': description: terms successfully accepted '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '501': "$ref": "#/components/responses/InternalServerError" "/user": delete: tags: - User operationId: DeleteCurrentUser security: - OAuth2: - user:user:delete - OIDC: - user:user:delete summary: Deletes the current account description: | The user deletion is implemented according to GDPR regulation. An account OTP is required to perform the action. requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/PlainOTP" responses: '202': description: Deletion process started '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" '501': "$ref": "#/components/responses/InternalServerError" "/user/pin": get: tags: - Credentials operationId: CheckUserPIN security: - OAuth2: - user:users.pin:check - OIDC: - user:users.pin:check summary: Check if user has a PIN description: 'This call can be used to check if the user PIN is set. ' parameters: - in: query name: timeout description: Timeout in seconds, wait until PIN is set (long polling) schema: type: integer example: 60 minimum: 1 maximum: 60 responses: '200': description: PIN is set '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" '501': "$ref": "#/components/responses/InternalServerError" put: tags: - Credentials operationId: UpdateUserPIN security: - OAuth2: - user:users.pin:update - OIDC: - user:users.pin:update summary: Set the new PIN description: | Sets the PIN of the user. The user has to select a secure PIN, this is ensured via rules. If one of the rules fails `406` is returned. To set the PIN an account OTP needs to be provided. The following rules apply to verify the PIN: * must be 4 digits long * must use 3 different digits * must not be a numerical series (e.g. 1234, 4321, ...) requestBody: required: true content: application/vnd.api+json: schema: type: object properties: data: "$ref": "#/components/schemas/UserPINAndOTP" responses: '200': description: PIN updated '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '406': description: PIN not secure content: application/vnd.api+json: schema: "$ref": "#/components/schemas/Errors" '501': "$ref": "#/components/responses/InternalServerError" "/user/password": get: tags: - Credentials operationId: CheckUserPassword security: - OAuth2: - user:users.password:check - OIDC: - user:users.password:check summary: Check if user has a Password description: 'This call can be used to check if the user password is set. ' parameters: - in: query name: timeout description: Timeout in seconds, wait until password is set (long polling) schema: type: integer example: 60 minimum: 1 maximum: 60 responses: '200': description: Password is set '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" '501': "$ref": "#/components/responses/InternalServerError" put: tags: - Credentials operationId: CreateUserPassword security: - OAuth2: - user:users.password:create - OIDC: - user:users.password:create summary: Request to set a password description: 'This process can only set a password if the user doesn''t already have one. The user will receive an email to set the password. This process enabled for for 24h. The request can be issued multiple times. In case the user already has a password set `409` is returned. ' responses: '202': description: Password request received, confirmation pending. '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" '409': description: Password is already set content: application/vnd.api+json: schema: "$ref": "#/components/schemas/Errors" '501': "$ref": "#/components/responses/InternalServerError" "/user/email/verify": post: tags: - User operationId: VerifyEmail summary: Verify Email description: 'Verifies that the given Email is not already used. ' requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/Email" responses: '204': description: Email is not used. '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" '409': "$ref": "#/components/responses/Conflict" '429': "$ref": "#/components/responses/TooManyRequests" '501': "$ref": "#/components/responses/InternalServerError" "/user/password/reset": put: tags: - Credentials operationId: ResetPassword summary: Reset password for a user. description: | Reset password for recover User's password. If no recover pin is passed in the body user's payment methods will also be reset. parameters: - in: query required: false name: pin description: Recover pin schema: type: string example: '5746' responses: '204': description: Password successfully updated '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '501': "$ref": "#/components/responses/InternalServerError" "/user/pin-or-password": get: tags: - Credentials operationId: CheckUserPinOrPassword security: - OAuth2: - user:users.pin:check - user:users.password:check - OIDC: - user:users.pin:check - user:users.password:check summary: Check if user has a PIN or Password description: 'This call can be used to check if the user PIN or password is set and verified. ' responses: '200': description: PIN or password is set content: application/json: schema: "$ref": "#/components/schemas/PinOrPassword" '401': "$ref": "#/components/responses/Unauthorized" '501': "$ref": "#/components/responses/InternalServerError" "/user/phone": get: tags: - Phone operationId: CheckUserPhone security: - OAuth2: - user:users.phone:check - OIDC: - user:users.phone:check summary: Check if user has a phone number set. description: 'This call can be used to check if the user phone is set and verified. ' responses: '200': description: Phone number is set '201': description: Phone number is set but not verified '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" '501': "$ref": "#/components/responses/InternalServerError" put: tags: - Phone operationId: UpdateUserPhone security: - OAuth2: - user:users.phone:update - OIDC: - user:users.phone:update summary: Request a change of the users phone number description: | The endpoint will issue an email to the customer, to confirm the update of the phone number is valid. After confirmation by the user an SMS is send to the user to verify the phone number. The SMS contains a code, that needs to be provided to the [verify user phone](#operation/VerifyUserPhone) operation. Mailing the customer will be omitted for the first time (if there is no phone number set). If the process is not completed within 24h the process is canceled. requestBody: required: true content: application/vnd.api+json: schema: type: object properties: data: "$ref": "#/components/schemas/UpdateUserPhone" responses: '200': description: Phone number is set '201': description: Phone number is set but not verified '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" '501': "$ref": "#/components/responses/InternalServerError" "/user/phone/verify": put: tags: - Phone operationId: VerifyUserPhone security: - OAuth2: - user:users.phone:update - OIDC: - user:users.phone:update summary: Verifies the users phone number description: 'Verifies the phone number of the user using the code send via sms. ' requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/VerifyUserPhone" responses: '200': description: Phone number is validated '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" '501': "$ref": "#/components/responses/InternalServerError" "/users/{userId}": get: tags: - User operationId: GetUser security: - OAuth2: - user:users:read - OIDC: - user:users:read summary: Returns the user data for the given user parameters: - in: path name: userId schema: type: string format: uuid description: The ID of the user. example: c0daf39b-4df5-4241-9e7d-b1b85f829090 responses: '200': description: User found content: application/vnd.api+json: schema: type: object properties: data: "$ref": "#/components/schemas/User" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '501': "$ref": "#/components/responses/InternalServerError" delete: tags: - User operationId: DeleteUser security: - OAuth2: - user:users:delete - OIDC: - user:users:delete summary: Deletes a user identified by UUID description: The user deletion is implemented according to GDPR regulation. parameters: - in: path name: userId schema: type: string format: uuid description: The ID of the user. example: c0daf39b-4df5-4241-9e7d-b1b85f829090 responses: '202': description: Deletion process started '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" '501': "$ref": "#/components/responses/InternalServerError" put: tags: - User operationId: SetUser security: - OAuth2: - user:users:write - OIDC: - user:users:write summary: Set the user data of the given user. description: 'All fields of the user get set to the provided values. ' parameters: - in: path name: userId schema: type: string format: uuid description: The ID of the user. example: c0daf39b-4df5-4241-9e7d-b1b85f829090 responses: '200': description: UpdateUser content: application/vnd.api+json: schema: type: object properties: data: "$ref": "#/components/schemas/User" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '406': "$ref": "#/components/responses/NotAcceptable" '415': "$ref": "#/components/responses/UnsupportedMediaType" '422': "$ref": "#/components/responses/UnprocessableEntity" '501': "$ref": "#/components/responses/InternalServerError" patch: tags: - User operationId: UpdateUser security: - OAuth2: - user:users:write - OIDC: - user:users:write summary: Updates the user data of the given user description: | All provided fields of the user get set to the provided values. All omitted fields will be left untouched. The complete new user record will be returned. parameters: - in: path name: userId schema: type: string format: uuid description: The ID of the user. example: c0daf39b-4df5-4241-9e7d-b1b85f829090 responses: '200': description: UpdateUser content: application/vnd.api+json: schema: type: object properties: data: "$ref": "#/components/schemas/User" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '406': "$ref": "#/components/responses/NotAcceptable" '415': "$ref": "#/components/responses/UnsupportedMediaType" '422': "$ref": "#/components/responses/UnprocessableEntity" '501': "$ref": "#/components/responses/InternalServerError" "/user/devices/totp": post: tags: - TOTP operationId: CreateTOTP security: - OAuth2: - user:device-totps:create - user:device-totps:create-after-login - OIDC: - user:device-totps:create - user:device-totps:create-after-login summary: Create device TOTP description: 'A device TOTP token is created within 5 minutes of registration without PIN, password or an user OTP or it is created using either PIN, password or an user OTP. In case the PIN, password or OTP is invalid `403` is returned. If multiple values are provided first the OTP is checked, then the password, then the PIN. In case the one of the provided values is correct, a TOTP will be created. ' requestBody: required: true content: application/vnd.api+json: schema: type: object properties: data: "$ref": "#/components/schemas/DeviceTOTP" responses: '201': description: TOTP created. content: application/vnd.api+json: schema: type: object properties: data: "$ref": "#/components/schemas/DeviceTOTP" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '406': "$ref": "#/components/responses/NotAcceptable" '415': "$ref": "#/components/responses/UnsupportedMediaType" '422': "$ref": "#/components/responses/UnprocessableEntity" '500': "$ref": "#/components/responses/InternalServerError" "/user/otp/verify": post: tags: - TOTP operationId: VerifyOTP security: - OAuth2: - user:otp:verify - OIDC: - user:otp:verify summary: Verify OTP description: 'Verifies that the passed OTP is valid for the user account. In case the OTP is invalid a `404` is returned. ' requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/OTP" responses: '204': description: Valid OTP. '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" '406': "$ref": "#/components/responses/NotAcceptable" '415': "$ref": "#/components/responses/UnsupportedMediaType" '422': "$ref": "#/components/responses/UnprocessableEntity" '500': "$ref": "#/components/responses/InternalServerError" "/user/otp/sendmail": post: tags: - TOTP operationId: SendmailOTP security: - OAuth2: - user:otp:create - OIDC: - user:otp:create summary: Send OTP via Mail description: 'Generates a one time password (OTP) and sends it to the user via mail. ' responses: '204': description: Mail successfully sent. '401': "$ref": "#/components/responses/Unauthorized" '500': "$ref": "#/components/responses/InternalServerError" "/user/otp": post: tags: - TOTP operationId: CreateOTP security: - OAuth2: - user:otp:create - OIDC: - user:otp:create summary: Create OTP description: 'Verifies that the passed PIN or password is valid for the user account and generates a one time password (OTP). One of the provided values need to be valid. First check is on the password, 2nd on the PIN. ' requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateOTP" example: pin: '8299' responses: '201': description: Valid OTP. content: application/json: schema: "$ref": "#/components/schemas/CreateOTP" example: otp: '773829' expiresAt: '2021-04-12T23:20:50.52Z' '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" '406': "$ref": "#/components/responses/NotAcceptable" '415': "$ref": "#/components/responses/UnsupportedMediaType" '422': "$ref": "#/components/responses/UnprocessableEntity" '500': "$ref": "#/components/responses/InternalServerError" "/sessions/{sessionId}": put: tags: - Sessions operationId: UpdateSession security: - OAuth2: - user:sessions:update - OIDC: - user:sessions:update summary: Update session description: | Update the status for the current user session. In case the session is created an OTP for the user is created and send via email, the caller can verify the OTP using [VerifyOTP](#operation/VerifyOTP) or use the provided value. parameters: - in: path name: sessionId schema: type: string format: uuid description: The ID of the user session. example: ddac0bf6-e618-499e-b6ee-2c45530ea8ed requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/Session" responses: '200': description: OTP send. content: application/json: schema: "$ref": "#/components/schemas/CreateOTP" example: otp: '773829' expiresAt: '2021-04-12T23:20:50.52Z' '204': description: Session updated. '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" '500': "$ref": "#/components/responses/InternalServerError" "/preferences/{clientId}": get: tags: - Preferences operationId: GetAppPreferences security: - OAuth2: - user:preferences:read - OIDC: - user:preferences:read summary: Get the users app preferences description: | Requests the apps preferences for the user identified by the given token. The preferences may only be returned if the client has the respective scope or is identified by the `clientId`. In order words all clients have their own preferences namespace, only with the respective scope e.g. `user:preferences:read:xyz` a client might be able to read the preferences of a different client. In case no preferences were ever set an empty object `{}` is returned. parameters: - in: path name: clientId schema: type: string description: The ID of the client for that the preferences should be read. example: xyz responses: '200': description: Retrieves the persisted preferences content: application/json: schema: type: object additionalProperties: true example: some: value everything: - is: up to: 123123 the: - client '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '501': "$ref": "#/components/responses/InternalServerError" put: tags: - Preferences operationId: UpdateAppPreferences security: - OAuth2: - user:preferences:write - OIDC: - user:preferences:write summary: Update the users app preferences description: | Updates the apps preferences for the user identified by the given token. The preferences may only be updated if the client has the respective scope or is identified by the `clientId`. In order words all clients have their own preferences namespace, only with the respective scope e.g. `user:preferences:read:xyz` a client might be able to read the preferences of a different client. The preferences should not have more than 10 key-value pairs per app. Any key must not be longer than 128 bytes and any value not longer than 10 megabytes (including complex json objects). parameters: - in: path name: clientId schema: type: string description: The ID of the client for that the preferences should be read. example: xyz requestBody: required: true content: application/json: schema: type: object additionalProperties: true example: some: value everything: - is: up to: 123123 the: - client responses: '204': description: Preferences updated. '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '413': description: Max number of keys exceeded content: application/vnd.api+json: schema: "$ref": "#/components/schemas/Errors" '501': "$ref": "#/components/responses/InternalServerError" "/attributes": get: tags: - Attributes operationId: GetUserAttributes security: - OAuth2: - user:attributes:read - OIDC: - user:attributes:read summary: Get the users keycloak attributes description: | Requests a list of attributes as set in keycloak, assuming the client has the required scope. parameters: [] responses: '200': description: Retrieves the persisted attributes content: application/json: schema: type: object additionalProperties: true example: tos_accepted: 'true' referred: 'false' '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '501': "$ref": "#/components/responses/InternalServerError" put: tags: - Attributes operationId: SetUserAttributes security: - OAuth2: - user:attributes:write - OIDC: - user:attributes:write summary: Update the users attributes description: | Updates the attributes of the user identified by the given token. Assuming the client has the required scope, it will update the attributes with any new keys, updating conflicting keys and leaving the rest untouched. requestBody: required: true content: application/json: schema: type: object additionalProperties: true example: tos_accepted: 'true' referred: 'false' responses: '204': description: Attributes updated '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '501': "$ref": "#/components/responses/InternalServerError" "/protocol/openid-connect/token": post: operationId: TokenExchange tags: - OAuth2 summary: Exchange User Token description: | Creates a PACE token for a foreign token using the OIDC token-exchange. The token provided **must** include the following claims (see https://datatracker.ietf.org/doc/html/rfc7519#page-9): * Claim `aud`: e.g. `"api.pace.cloud"` audience of this token is PACE API, has to match the host requested via HTTP. In development or other environments the URL may be different therefore, e.g. `"api.dev.pace.cloud"`. * Claim `iss`: e.g. `"https://as.example.com"` the issuer of the token, issuer needs to be known to PACE * Claim `iat`: e.g. `1516239022` time the token was issued * Claim `exp`: e.g. `1516249022` identifies the expiration time on or after which the JWT MUST NOT be accepted for processing * Claim `sub`: e.g. `"03836e1f-58ed-4d67-baa0-a73bf77b9d5d"` unique account id on the issuer side * Claim `email`: e.g. `"03836e1f-58ed-4d67-baa0-a73bf77b9d5d@as.example.com"` usually an account proxy email (will receive SMTP mails). Usually subject ID + issuer domain to provide a unique account id. Optionally the token may contain: * Claim `name`: e.g. `"Jane Doe"` full name of the user (used in emails addressed to the proxy) * Claim `given_name`: e.g. `"Jane"` given name of the user * Claim `family_name`: e.g. `"Doe"` family name of the user * Claim `locale`: e.g. `"de"` or `"en-US"` language code of the user (format ISO 639-1 Alpha-2 [ISO639‑1] language code in lowercase and an ISO 3166-1 Alpha-2 [ISO3166‑1] country code in uppercase, separated by a dash) defaults to `"en"` * Claim `zoneinfo`: e.g. `"Europe/Paris"` timezone information defaults to `"Europe/Berlin"` (TZ database) RFCs for reference: * https://datatracker.ietf.org/doc/html/rfc8693 * https://datatracker.ietf.org/doc/html/rfc7519 requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/OAuth2TokenExchange" application/x-www-form-urlencoded: schema: "$ref": "#/components/schemas/OAuth2TokenExchange" example: 'client_idawesome-app&client_secretaad041a4-47f0-4b01-80d3-edce807fec82&grant_typeurn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange&subject_tokeneyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIwMzgzNm%20UxZi01OGVkLTRkNjctYmFhMC1hNzNiZjc3YjlkNWQiLCJhdWQiOiJhc%20GkuZGV2LnBhY2UuY2xvdWQiLCJuYW1lIjoiSmFuZSBEb2UiLCJnaXZl%20bl9uYW1lIjoiSmFuZSIsImZhbWlseV9uYW1lIjoiRG9lIiwiaXNzIjo%20iaHR0cHM6Ly9hcy5leGFtcGxlLmNvbSIsImlhdCI6MTUxNjIzOTAyMi%20wiZXhwIjoxNTE2MjQ5MDIyLCJlbWFpbCI6IjAzODM2ZTFmLTU4ZWQtN%20GQ2Ny1iYWEwLWE3M2JmNzdiOWQ1ZEBhcy5leGFtcGxlLmNvbSJ9.Z1t%20-0dayzXl069Bwt5bHlgpV0WlZUKF5ma7X1Uo-e3o%0A&subject_issuerhttps%3A//as.example.com&subject_token_typeurn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token&audienceawesome-app ' responses: '200': description: PACE Access Token. content: application/json: schema: "$ref": "#/components/schemas/OAuth2Token" '401': description: 'The authorization of the client is invalid. ' content: application/json: schema: "$ref": "#/components/schemas/OAuth2Error" '403': description: 'The token is not trusted and therefore rejected. ' content: application/json: schema: "$ref": "#/components/schemas/OAuth2Error" '422': description: 'The request was rejected due to invalid request data, e.g. invalid token content. ' content: application/json: schema: "$ref": "#/components/schemas/OAuth2Error" '500': description: 'Internal Server Error. ' content: application/json: schema: "$ref": "#/components/schemas/OAuth2Error" "/federated-identities/{identityProvider}": put: tags: - FederatedIdentity operationId: SetFederatedIdentity security: - OAuth2: - user:federated-identity:set - OIDC: - user:federated-identity:set summary: Define federated identity description: 'Set a federated identity for the user with the given identity provider ' parameters: - in: path name: identityProvider schema: type: string description: The name of the identity provider example: mobypay responses: '204': description: Identity set. '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" '500': "$ref": "#/components/responses/InternalServerError" delete: tags: - FederatedIdentity operationId: DeleteFederatedIdentity security: - OAuth2: - user:federated-identity:delete - OIDC: - user:federated-identity:delete summary: Delete federated identity description: 'Delete federated identity for the user with the given identity provider ' parameters: - in: path name: identityProvider schema: type: string description: The name of the identity provider example: mobypay responses: '204': description: Identity deleted. '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" '500': "$ref": "#/components/responses/InternalServerError" "/federated-identities/{identityProvider}/token": post: tags: - FederatedIdentity - OAuth2 operationId: GrantFederatedToken summary: Provide a token for a federated identity provider description: 'Provides a token for the given identity provider, if the user has a valid one. Token grant is a request as per OAuth2 specification ' parameters: - in: path name: identityProvider schema: type: string description: The name of the identity provider example: mobypay responses: '200': description: Token granted content: application/json: schema: "$ref": "#/components/schemas/AccessToken" '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" '500': "$ref": "#/components/responses/InternalServerError" "/callbacks/password-reset": post: tags: - Callbacks operationId: CallbackPasswordReset security: - OAuth2: - user:callbacks:password-reset - OIDC: - user:callbacks:password-reset summary: Password reset description: | During a password reset the user is only able to provide the HAVE using the email address. In order to retain the user data the user has to provide a second factor, either HAVE or KNOW. The `prove` can be done with *PIN* (KNOW) or the *device OTP* (HAVE). This callback is called before the password of the user is reset. If the user is able to provide his/her `prove` correctly the data of the user remain untouched. In case the `prove` is in correctly provided for more than 3 times, the critical data e.g. payment data of the user is deleted in order to prevent theft. * `404` is returned in case the user has no `prove` defined. * `410` is returned in case the `prove` didn't match multiple times, the user data will be deleted for safety reasons. * `422` is returned in case the the `prove` is incorrect. requestBody: required: true content: application/vnd.api+json: schema: "$ref": "#/components/schemas/UserPIN" responses: '204': description: PIN is correct, data will be retained '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '410': "$ref": "#/components/responses/Gone" '422': "$ref": "#/components/responses/UnprocessableEntity" '501': "$ref": "#/components/responses/InternalServerError" "/auditlogs/record": post: tags: - AuditLog operationId: RecordAuditLog summary: Record audit log action description: 'Record actions of a user. ' responses: '204': description: Record accepted content: application/json: schema: "$ref": "#/components/schemas/AuditLogRecord" '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" '500': "$ref": "#/components/responses/InternalServerError" "/maintenance/check-scopes": post: tags: - Maintenance description: Compares the scopes between our api-definitions and Keycloak requestBody: required: true content: application/vnd.api+json: schema: type: object properties: data: "$ref": "#/components/schemas/Scopes" responses: '200': description: check scopes succeded content: application/vnd.api+json: schema: type: object properties: data: "$ref": "#/components/schemas/Scopes" '401': "$ref": "#/components/responses/Unauthorized" '501': "$ref": "#/components/responses/InternalServerError" components: schemas: Errors: type: object description: | Error objects provide additional information about problems encountered while performing an operation. Errors also contain codes besides title and message which can be used for checks even if the detailed messages might change. * `1000`: generic error * `1001`: payment processing temporarily unavailable * `1002`: requested amount exceeds the authorized amount of the provided token * `1003`: implicit payment methods cannot be modified * `1004`: payment method rejected by provider * `provider:payment-method-rejected`: payment method rejected by provider (identical to `1004`) * `rule:product-denied`: Product restrictions forbid transaction, e.g., forbidden fuel type - token authorized only for Diesel but attempted to fuel Super. properties: errors: type: array items: type: object properties: id: type: string description: A unique identifier for this particular occurrence of the problem. links: type: object properties: about: type: string description: 'A link that leads to further details about this particular occurrence of the problem. ' status: type: string description: 'the HTTP status code applicable to this problem, expressed as a string value. ' code: type: string description: 'an application-specific error code, expressed as a string value. ' title: type: string description: 'A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. ' detail: type: string description: 'a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. ' source: type: object description: 'An object containing references to the source of the error. ' properties: pointer: type: string description: 'A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. ' parameter: type: string description: 'A string indicating which URI query parameter caused the error. ' meta: type: object description: 'a meta object containing non-standard meta-information about the error. ' properties: {} additionalProperties: true Scopes: type: object properties: type: type: string enum: - scopes id: type: string example: d6e06f46-5dd8-47d9-a5bc-e28fad440dd1 attributes: type: object properties: scopes: type: array items: type: string example: user:callbacks:password-reset UserPINAndOTP: type: object properties: type: type: string enum: - pin id: type: string attributes: type: object required: - pin - otp properties: pin: type: string description: 4-digit code example: '5621' writeOnly: true otp: type: string description: user otp example: '526271' writeOnly: true UserPIN: type: object properties: pin: type: string description: 4-digit code example: '5621' writeOnly: true skip: type: boolean description: allows skipping credential verification example: true writeOnly: true UpdateUserPhone: type: object properties: type: type: string enum: - phone id: type: string attributes: type: object required: - phoneNumber properties: phoneNumber: type: string description: complete phone number of the user example: "+49 170 888 999 000" VerifyUserPhone: type: object properties: code: type: string description: the code that was send to the user via SMS example: '748938' DeviceTOTP: type: object properties: type: type: string enum: - deviceTOTP id: type: string format: uuid description: The ID of the device totp example: 738e379f-fe30-45ab-819c-ba88804b6368 attributes: type: object properties: pin: type: string description: user account PIN example: '8299' writeOnly: true password: type: string description: user account password example: superSecret12345! writeOnly: true otp: type: string description: user otp example: '526271' writeOnly: true secret: type: string description: TOTP secret to generate TOTP tokens (encoded base32) example: PBVDSNDDKZ4HGZ3UG5CHUUSEMJCTCSCU readOnly: true period: type: integer description: Number of seconds a TOTP hash is valid for. example: 30 readOnly: true digits: type: integer description: Required length of the generated OTP example: 6 readOnly: true algorithm: type: string description: Algorithm to use for HMAC example: SHA1 enum: - SHA1 - SHA256 - SHA512 - MD5 readOnly: true CreateOTP: type: object properties: pin: type: string description: user account PIN example: '8299' writeOnly: true password: type: string description: user account password example: superSecret12345! writeOnly: true otp: type: string description: one time password example: '773829' readOnly: true expiresAt: type: string format: date-time example: '2021-04-12T23:20:50.52Z' readOnly: true PlainOTP: type: object properties: otp: type: string description: one time password example: '773829' writeOnly: true AuditLogRecord: type: object properties: service: type: string example: pay description: Name of the service this action was performed on, e.g., pay or fueling actionName: type: string example: list_transactions resource: type: object properties: identifier: type: string description: Identifier of the resource resourceType: type: string example: transaction actionData: type: object actionDate: type: string format: date-time description: Date the action happened AccessToken: type: object properties: access_token: type: string token_type: type: string refresh_token: type: string description: Optional. Token for refreshing this grant expires_in: type: integer description: Number of seconds the token is valid scope: type: string Email: type: object properties: email: type: string description: The email the user wants to use. example: user@pace.car OTP: type: object properties: otp: type: string description: one time password example: '773829' writeOnly: true types: type: array description: | the one time password type to validate against. If none provided all default types are checked. * `login` login otp ([created and send via email](#operation/SendUsersLoginOTP)) * `account` user account otp ([created on demand via pin / password](#operation/CreateOTP).) * `totp` user provided TOTP (authenticator) * `device-totp` device TOTP ([e.g. PACE Drive App, PACE Car App](#operation/CreateTOTP)) writeOnly: true default: - device-totp - account items: type: string enum: - login - account - totp - device-totp Session: type: object properties: userId: type: string format: uuid description: The ID of the user that owns the session example: 738e379f-fe30-45ab-819c-ba88804b6368 passedLoginOTP: type: boolean description: sets the login otp to true (passed) or false (not passed) example: true writeOnly: true PinOrPassword: type: object properties: pin: type: boolean description: indicates if PIN is set and validated example: false readOnly: true password: type: boolean description: indicates if password is set and validated example: true readOnly: true User: type: object properties: type: type: string enum: - User id: type: string format: uuid description: User ID example: c0daf39b-4df5-4241-9e7d-b1b85f829090 attributes: type: object properties: firstName: type: string example: John lastName: type: string example: Smith email: type: string format: email example: user@example.com phoneNumber: type: string example: "+1 (425) 555-1212" description: 'End-User''s preferred telephone number. E.164 [E.164] is RECOMMENDED as the format of this Claim, for example, +1 (425) 555-1212 or +56 (2) 687 2400. If the phone number contains an extension, it is RECOMMENDED that the extension be represented using the RFC 3966 [RFC3966] extension syntax, for example, +1 (604) 555-1234;ext=5678. ' pictureUrl: type: string example: https://api.pace.cloud/user/img/uztqwenbqw87t123jhg87t6876 gender: type: string description: End-User's gender. Values defined by this specification are `female` and `male`. `other` should be used in all other cases. enum: - male - female - other createdAt: type: string format: date-time description: time of the user creation example: '2021-09-01T23:12:56Z' readOnly: true birthDate: type: string format: date example: '1997-07-21T00:00:00.000Z' description: 'End-User''s birthday, represented as an ISO 8601:2004 [ISO8601‑2004] `YYYY-MM-DD` format. The year MAY be `0000`, indicating that it is omitted. To represent only the year, `YYYY` format is allowed. Note that depending on the underlying platform''s date related function, providing just year can result in varying month and day, so the implementers need to take this factor into account to correctly process the dates. ' address: type: object properties: country: type: string example: DE description: ISO 3166 Codes (Alpha 2) locality: type: string example: Karlsruhe street: type: string example: Haid-und-Neu-Straße houseNo: type: string example: 18 additionalAddressLink: type: string example: z.H. John Smith region: type: string example: BW postalCode: type: string example: 76131 locale: type: string example: de-DE description: 'End-User''s locale, represented as a BCP47 [RFC5646] language tag. This is typically an ISO 639-1 Alpha-2 [ISO639‑1] language code in lowercase and an ISO 3166-1 Alpha-2 [ISO3166‑1] country code in uppercase, separated by a dash. For example, en-US or fr-CA. As a compatibility note, some implementations have used an underscore as the separator rather than a dash, for example, en_US; Relying Parties MAY choose to accept this locale syntax as well. ' zoneInfo: type: string example: Europe/Berlin description: Timezone as per tz database. Terms: type: object properties: type: type: string enum: - Terms id: type: string format: uuid description: Terms ID example: 6d876562-625d-47bb-964b-25b52d6ef521 attributes: type: object properties: version: type: number example: 202004201530 acceptUrl: type: string description: Location to the terms of service that need to be accepted example: "/api/terms/6d876562-625d-47bb-964b-25b52d6ef521/accept" markdown: type: string description: Terms of service formatted as markdown example: | # Lorem ipsum Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque volutpat congue ante non elementum. Suspendisse potenti. Nulla facilisi. Donec euismod purus at risus ultricies, quis ullamcorper nulla porttitor. Vestibulum at dui pulvinar, consequat metus ultricies, auctor libero. Nulla facilisi. Suspendisse euismod elementum diam, sit amet tempus est. Quisque congue ligula at interdum accumsan. Suspendisse porttitor erat nibh, at pellentesque sem aliquet eget. Quisque posuere libero in velit lobortis, id elementum arcu faucibus. Nullam vulputate neque turpis, vitae sollicitudin elit scelerisque vitae. Cras sit amet justo vitae est vestibulum ullamcorper. Aenean lobortis metus sed sem imperdiet vestibulum. Nullam cursus orci non nibh sodales lobortis. **Proin eros metus, commodo nec facilisis at, sodales id ipsum. Etiam gravida ante vel leo placerat, non elementum libero placerat.** Quisque et tellus ac est accumsan venenatis egestas et risus. Proin vel tellus eu magna cursus dictum et eu erat. Quisque ultrices est a nulla accumsan, eu facilisis lorem maximus. Integer ut turpis pharetra lectus pellentesque ultricies sed eget tellus. Proin id ipsum vel ante tempor dapibus ac eget mauris. Aliquam auctor at nisl vitae rutrum. ## 1 Ipsum Lorem Duis id vestibulum elit. Fusce ut neque at arcu lacinia rutrum. Mauris quis facilisis dui. Sed pharetra est mauris, vel convallis nulla vestibulum non. Mauris vulputate sit amet dolor ut convallis. Cras hendrerit in tellus nec dictum. Aliquam eleifend, lectus eu feugiat accumsan, nulla diam volutpat tellus, sed bibendum ligula nisi ac lectus. Etiam a cursus leo. Nam lectus est, lacinia eu mi ut, hendrerit scelerisque nisl. Nunc sit amet aliquet est. Fusce euismod consequat interdum. Nunc maximus molestie sem, ac dignissim sem pellentesque id. Nulla facilisi. Nullam suscipit nisl metus, ac bibendum neque fermentum ac. Vivamus venenatis placerat elit eu dictum. Nullam at iaculis magna. Vivamus rutrum arcu quis ligula sollicitudin sagittis. In hac habitasse platea dictumst. Quisque nec finibus elit, ac rutrum elit. Ut et felis eget dolor interdum posuere. ## 2 Lorem Lorem Nulla fringilla aliquam tortor eu pulvinar. Maecenas posuere tortor ac sem faucibus ullamcorper. Nullam faucibus eget ipsum at mattis. Phasellus tempor euismod sem et finibus. Sed eros quam, consequat sit amet metus at, aliquam luctus diam. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia curae; Sed et erat nec tellus malesuada consequat. Maecenas odio sem, hendrerit id felis ac, tincidunt vestibulum magna. Nullam ut vulputate odio. Cras nibh mauris, condimentum nec efficitur nec, fermentum sed elit. Vivamus a nunc eget ante mattis vehicula non eu eros. Donec blandit lobortis ipsum, vitae feugiat dolor dignissim vel. Proin est nibh, efficitur in mi sit amet, placerat convallis libero. In ac purus at justo ornare euismod et vitae libero. Ut suscipit mi in tempor lobortis. OAuth2TokenExchange: type: object required: - client_id - client_secret - grant_type - subject_token - subject_issuer - subject_token_type properties: client_id: type: string description: 'This parameter is required for clients using form parameters for authentication. ' example: awesome-app client_secret: type: string description: | This parameter is required for clients using form parameters for authentication and using a client secret as a credential. example: aad041a4-47f0-4b01-80d3-edce807fec82 grant_type: type: string description: 'The value of the parameter must be `urn:ietf:params:oauth:grant-type:token-exchange`. ' enum: - urn:ietf:params:oauth:grant-type:token-exchange example: urn:ietf:params:oauth:grant-type:token-exchange subject_token: type: string description: | A security token that represents the identity of the party on behalf of whom the request is being made. It is required if you are exchanging an existing token for a new one. example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIwMzgzNm UxZi01OGVkLTRkNjctYmFhMC1hNzNiZjc3YjlkNWQiLCJhdWQiOiJhc GkuZGV2LnBhY2UuY2xvdWQiLCJuYW1lIjoiSmFuZSBEb2UiLCJnaXZl bl9uYW1lIjoiSmFuZSIsImZhbWlseV9uYW1lIjoiRG9lIiwiaXNzIjo iaHR0cHM6Ly9hcy5leGFtcGxlLmNvbSIsImlhdCI6MTUxNjIzOTAyMi wiZXhwIjoxNTE2MjQ5MDIyLCJlbWFpbCI6IjAzODM2ZTFmLTU4ZWQtN GQ2Ny1iYWEwLWE3M2JmNzdiOWQ1ZEBhcy5leGFtcGxlLmNvbSJ9.Z1t -0dayzXl069Bwt5bHlgpV0WlZUKF5ma7X1Uo-e3o ' subject_issuer: type: string description: 'Identifies the issuer of the subject_token. The same as the tokens `iss` value. Usually a URL. ' example: https://as.example.com subject_token_type: type: string description: | This parameter represents the type of token the client wants to exchange for. Currently only oauth and OpenID Connect token types are supported specifically `urn:ietf:params:oauth:token-type:access_token`. enum: - urn:ietf:params:oauth:token-type:access_token example: urn:ietf:params:oauth:token-type:access_token audience: type: string description: | This parameter specifies the target client you want the new token minted for. This will be part of the token in the `aud` field. If left blank it will be the same as the provided `client_id`. example: awesome-app scope: type: string description: | This parameter represents the target set of OAuth and OpenID Connect scopes the client is requesting. This parameter ensures to the client that the token is only provided in case the requested scopes are part of it. More scopes may be returned. example: '' OAuth2Token: type: object required: - access_token - issued_token_type - token_type - expires_in properties: access_token: type: string description: '' example: 'eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJnYlpySmRJelBTTWN 1aHNJYzZfM3g3ZmhrdTM4UmN5MlZLVUZ4LWppNTNzIn0.eyJleHAiOjE2MjU4MzcyOT AsImlhdCI6MTYyNTgzMDA5MCwiYXV0aF90aW1lIjoxNjI1ODMwMDQ4LCJqdGkiOiIyM 2FiNzEwMC0xZGZkLTQwYTktYTE3YS01MjUwN2ZlYWFiY2IiLCJpc3MiOiJodHRwczov L2lkLmRldi5wYWNlLmNsb3VkL2F1dGgvcmVhbG1zL3BhY2UiLCJzdWIiOiI1YWE2NWY 1NC01NjdmLTQ2ZTUtYWRkOS05OGIxMjQ0YjUzMTYiLCJ0eXAiOiJCZWFyZXIiLCJhen AiOiJ2aW5jZW50LXRlc3QtMiIsInNlc3Npb25fc3RhdGUiOiIzYTMwMDM1OC0xMzIyL TRlYzktYWI3My1kYjM5MjUwYzIzZjQiLCJhY3IiOiIwIiwic2NvcGUiOiJka3ZjYXJk OnBheW1lbnQtbWV0aG9kOmFkZCB1c2VyOnVzZXIuZW1haWw6cmVhZCB1c2VyOnByZWZ lcmVuY2VzOndyaXRlIHVzZXI6cHJlZmVyZW5jZXM6cmVhZCBmdWVsY2FyZDpjYXJkcz pyZWFkIHBvaTpnYXMtc3RhdGlvbnM6cmVhZCBka3ZjYXJkOmNhcmRzOnJlYWQgZGt2Y 2FyZDpwYXltZW50LW1ldGhvZDpyZW1vdmUiLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwi bG9jYWxlIjoiZGUiLCJlbWFpbCI6ImphbmUuZG9lQGV4YW1wbGUtcGFsY2UtaW4tdGh lLXd3dy5jb20ifQ.mp4mkpPPMpFfZa5cYiTDM8HxFsEMKVm_B6ujh_629sHc6D7iaCg jUZ2VNwGyxDS2Z_XZ-b2PoLVLHJOS2shBVS7p-kx7fFuCCMA9Um-3RpIzfVNyYbNiHX T2DG146845Jxdfa5S3nAuaD5_aFOKEcQQpXEMqVm5QTfD1cU8ne61mOF34_CbW_c7kX bVJKCYv-qg0LzKfhO6xeGe5ovo3-QWZCXtQmhsCcK2HnQ6kgDLAK_vdSHkvNR3lEv_i H83DyqGysXvVdvT6f25CcVabTBCcnpyKHC3765p_tkZ2digX_qm8KBVKIAN00UP6f2V c0VEGKIAlfNZlC1hMpWxCEA ' issued_token_type: type: string description: The type of the token issued as described. enum: - urn:ietf:params:oauth:token-type:jwt example: urn:ietf:params:oauth:token-type:jwt token_type: type: string description: | The type of the token issued as described in https://datatracker.ietf.org/doc/html/rfc6749#section-7.1. Value is case insensitive. example: urn:ietf:params:oauth:token-type:access_token expires_in: type: number description: | The lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated. If omitted, the authorization server SHOULD provide the expiration time via other means or document the default value. example: 7200 OAuth2Error: type: object properties: error: type: string description: | A single ASCII [USASCII] error code from the following: **invalid_request** The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed. **invalid_client** Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the "Authorization" request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the "WWW-Authenticate" response header field matching the authentication scheme used by the client. **invalid_grant** The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. **unauthorized_client** The authenticated client is not authorized to use this authorization grant type. **unsupported_grant_type** The authorization grant type is not supported by the authorization server. enum: - invalid_request - invalid_client - invalid_grant - unauthorized_client - unsupported_grant_type error_description: type: string description: | Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred. Values for the "error_description" parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E. error_uri: type: string description: | A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error. Values for the "error_uri" parameter MUST conform to the URI-reference syntax and thus MUST NOT include characters outside the set %x21 / %x23-5B / %x5D-7E. responses: BadGateway: description: Error occurred while communicating with upstream services content: application/vnd.api+json: schema: "$ref": "#/components/schemas/Errors" Unauthorized: description: | OAuth token missing or invalid or a linked identity is missing. Linked identity missing is a special case where you need to make sure that the user has additionally logged in / authorized with a third-party. This is not relevant for most use-cases. The specific error code that identifies a missing linked identity is `missing-linked-identity` Example: ``` { "errors": [ { "id": "cbgmhslmp1o9or9kh1p0", "title": "Missing linked identity for authorized access", "detail": "Linked identity is needed to access this resource, please check why the user does not have a linked identity", "status": "401", "code": "missing-linked-identity" } ] } ``` content: application/vnd.api+json: schema: type: object description: | Error objects provide additional information about problems encountered while performing an operation. Errors also contain codes besides title and message which can be used for checks even if the detailed messages might change. * `1000`: generic error * `1001`: payment processing temporarily unavailable * `1002`: requested amount exceeds the authorized amount of the provided token * `1003`: implicit payment methods cannot be modified * `1004`: payment method rejected by provider * `provider:payment-method-rejected`: payment method rejected by provider (identical to `1004`) * `rule:product-denied`: Product restrictions forbid transaction, e.g., forbidden fuel type - token authorized only for Diesel but attempted to fuel Super. properties: errors: type: array items: type: object properties: id: type: string description: A unique identifier for this particular occurrence of the problem. links: type: object properties: about: type: string description: 'A link that leads to further details about this particular occurrence of the problem. ' status: type: string description: 'the HTTP status code applicable to this problem, expressed as a string value. ' code: type: string description: 'an application-specific error code, expressed as a string value. ' title: type: string description: 'A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. ' detail: type: string description: 'a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. ' source: type: object description: 'An object containing references to the source of the error. ' properties: pointer: type: string description: 'A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. ' parameter: type: string description: 'A string indicating which URI query parameter caused the error. ' meta: type: object description: 'a meta object containing non-standard meta-information about the error. ' properties: {} additionalProperties: true Forbidden: description: Forbidden content: application/vnd.api+json: schema: type: object description: | Error objects provide additional information about problems encountered while performing an operation. Errors also contain codes besides title and message which can be used for checks even if the detailed messages might change. * `1000`: generic error * `1001`: payment processing temporarily unavailable * `1002`: requested amount exceeds the authorized amount of the provided token * `1003`: implicit payment methods cannot be modified * `1004`: payment method rejected by provider * `provider:payment-method-rejected`: payment method rejected by provider (identical to `1004`) * `rule:product-denied`: Product restrictions forbid transaction, e.g., forbidden fuel type - token authorized only for Diesel but attempted to fuel Super. properties: errors: type: array items: type: object properties: id: type: string description: A unique identifier for this particular occurrence of the problem. links: type: object properties: about: type: string description: 'A link that leads to further details about this particular occurrence of the problem. ' status: type: string description: 'the HTTP status code applicable to this problem, expressed as a string value. ' code: type: string description: 'an application-specific error code, expressed as a string value. ' title: type: string description: 'A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. ' detail: type: string description: 'a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. ' source: type: object description: 'An object containing references to the source of the error. ' properties: pointer: type: string description: 'A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. ' parameter: type: string description: 'A string indicating which URI query parameter caused the error. ' meta: type: object description: 'a meta object containing non-standard meta-information about the error. ' properties: {} additionalProperties: true RequestTimeout: description: Your request timed out content: application/vnd.api+json: schema: type: object description: | Error objects provide additional information about problems encountered while performing an operation. Errors also contain codes besides title and message which can be used for checks even if the detailed messages might change. * `1000`: generic error * `1001`: payment processing temporarily unavailable * `1002`: requested amount exceeds the authorized amount of the provided token * `1003`: implicit payment methods cannot be modified * `1004`: payment method rejected by provider * `provider:payment-method-rejected`: payment method rejected by provider (identical to `1004`) * `rule:product-denied`: Product restrictions forbid transaction, e.g., forbidden fuel type - token authorized only for Diesel but attempted to fuel Super. properties: errors: type: array items: type: object properties: id: type: string description: A unique identifier for this particular occurrence of the problem. links: type: object properties: about: type: string description: 'A link that leads to further details about this particular occurrence of the problem. ' status: type: string description: 'the HTTP status code applicable to this problem, expressed as a string value. ' code: type: string description: 'an application-specific error code, expressed as a string value. ' title: type: string description: 'A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. ' detail: type: string description: 'a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. ' source: type: object description: 'An object containing references to the source of the error. ' properties: pointer: type: string description: 'A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. ' parameter: type: string description: 'A string indicating which URI query parameter caused the error. ' meta: type: object description: 'a meta object containing non-standard meta-information about the error. ' properties: {} additionalProperties: true BadRequest: description: Bad request content: application/vnd.api+json: schema: type: object description: | Error objects provide additional information about problems encountered while performing an operation. Errors also contain codes besides title and message which can be used for checks even if the detailed messages might change. * `1000`: generic error * `1001`: payment processing temporarily unavailable * `1002`: requested amount exceeds the authorized amount of the provided token * `1003`: implicit payment methods cannot be modified * `1004`: payment method rejected by provider * `provider:payment-method-rejected`: payment method rejected by provider (identical to `1004`) * `rule:product-denied`: Product restrictions forbid transaction, e.g., forbidden fuel type - token authorized only for Diesel but attempted to fuel Super. properties: errors: type: array items: type: object properties: id: type: string description: A unique identifier for this particular occurrence of the problem. links: type: object properties: about: type: string description: 'A link that leads to further details about this particular occurrence of the problem. ' status: type: string description: 'the HTTP status code applicable to this problem, expressed as a string value. ' code: type: string description: 'an application-specific error code, expressed as a string value. ' title: type: string description: 'A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. ' detail: type: string description: 'a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. ' source: type: object description: 'An object containing references to the source of the error. ' properties: pointer: type: string description: 'A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. ' parameter: type: string description: 'A string indicating which URI query parameter caused the error. ' meta: type: object description: 'a meta object containing non-standard meta-information about the error. ' properties: {} additionalProperties: true Gone: description: Resource is gone content: application/vnd.api+json: schema: type: object description: | Error objects provide additional information about problems encountered while performing an operation. Errors also contain codes besides title and message which can be used for checks even if the detailed messages might change. * `1000`: generic error * `1001`: payment processing temporarily unavailable * `1002`: requested amount exceeds the authorized amount of the provided token * `1003`: implicit payment methods cannot be modified * `1004`: payment method rejected by provider * `provider:payment-method-rejected`: payment method rejected by provider (identical to `1004`) * `rule:product-denied`: Product restrictions forbid transaction, e.g., forbidden fuel type - token authorized only for Diesel but attempted to fuel Super. properties: errors: type: array items: type: object properties: id: type: string description: A unique identifier for this particular occurrence of the problem. links: type: object properties: about: type: string description: 'A link that leads to further details about this particular occurrence of the problem. ' status: type: string description: 'the HTTP status code applicable to this problem, expressed as a string value. ' code: type: string description: 'an application-specific error code, expressed as a string value. ' title: type: string description: 'A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. ' detail: type: string description: 'a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. ' source: type: object description: 'An object containing references to the source of the error. ' properties: pointer: type: string description: 'A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. ' parameter: type: string description: 'A string indicating which URI query parameter caused the error. ' meta: type: object description: 'a meta object containing non-standard meta-information about the error. ' properties: {} additionalProperties: true UnprocessableEntity: description: The request was well-formed but was unable to be followed due to semantic errors. content: application/vnd.api+json: schema: type: object description: | Error objects provide additional information about problems encountered while performing an operation. Errors also contain codes besides title and message which can be used for checks even if the detailed messages might change. * `1000`: generic error * `1001`: payment processing temporarily unavailable * `1002`: requested amount exceeds the authorized amount of the provided token * `1003`: implicit payment methods cannot be modified * `1004`: payment method rejected by provider * `provider:payment-method-rejected`: payment method rejected by provider (identical to `1004`) * `rule:product-denied`: Product restrictions forbid transaction, e.g., forbidden fuel type - token authorized only for Diesel but attempted to fuel Super. properties: errors: type: array items: type: object properties: id: type: string description: A unique identifier for this particular occurrence of the problem. links: type: object properties: about: type: string description: 'A link that leads to further details about this particular occurrence of the problem. ' status: type: string description: 'the HTTP status code applicable to this problem, expressed as a string value. ' code: type: string description: 'an application-specific error code, expressed as a string value. ' title: type: string description: 'A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. ' detail: type: string description: 'a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. ' source: type: object description: 'An object containing references to the source of the error. ' properties: pointer: type: string description: 'A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. ' parameter: type: string description: 'A string indicating which URI query parameter caused the error. ' meta: type: object description: 'a meta object containing non-standard meta-information about the error. ' properties: {} additionalProperties: true NotAcceptable: description: The specified accept header is invalid content: application/vnd.api+json: schema: type: object description: | Error objects provide additional information about problems encountered while performing an operation. Errors also contain codes besides title and message which can be used for checks even if the detailed messages might change. * `1000`: generic error * `1001`: payment processing temporarily unavailable * `1002`: requested amount exceeds the authorized amount of the provided token * `1003`: implicit payment methods cannot be modified * `1004`: payment method rejected by provider * `provider:payment-method-rejected`: payment method rejected by provider (identical to `1004`) * `rule:product-denied`: Product restrictions forbid transaction, e.g., forbidden fuel type - token authorized only for Diesel but attempted to fuel Super. properties: errors: type: array items: type: object properties: id: type: string description: A unique identifier for this particular occurrence of the problem. links: type: object properties: about: type: string description: 'A link that leads to further details about this particular occurrence of the problem. ' status: type: string description: 'the HTTP status code applicable to this problem, expressed as a string value. ' code: type: string description: 'an application-specific error code, expressed as a string value. ' title: type: string description: 'A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. ' detail: type: string description: 'a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. ' source: type: object description: 'An object containing references to the source of the error. ' properties: pointer: type: string description: 'A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. ' parameter: type: string description: 'A string indicating which URI query parameter caused the error. ' meta: type: object description: 'a meta object containing non-standard meta-information about the error. ' properties: {} additionalProperties: true InternalServerError: description: Internal server error content: application/vnd.api+json: schema: type: object description: | Error objects provide additional information about problems encountered while performing an operation. Errors also contain codes besides title and message which can be used for checks even if the detailed messages might change. * `1000`: generic error * `1001`: payment processing temporarily unavailable * `1002`: requested amount exceeds the authorized amount of the provided token * `1003`: implicit payment methods cannot be modified * `1004`: payment method rejected by provider * `provider:payment-method-rejected`: payment method rejected by provider (identical to `1004`) * `rule:product-denied`: Product restrictions forbid transaction, e.g., forbidden fuel type - token authorized only for Diesel but attempted to fuel Super. properties: errors: type: array items: type: object properties: id: type: string description: A unique identifier for this particular occurrence of the problem. links: type: object properties: about: type: string description: 'A link that leads to further details about this particular occurrence of the problem. ' status: type: string description: 'the HTTP status code applicable to this problem, expressed as a string value. ' code: type: string description: 'an application-specific error code, expressed as a string value. ' title: type: string description: 'A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. ' detail: type: string description: 'a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. ' source: type: object description: 'An object containing references to the source of the error. ' properties: pointer: type: string description: 'A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. ' parameter: type: string description: 'A string indicating which URI query parameter caused the error. ' meta: type: object description: 'a meta object containing non-standard meta-information about the error. ' properties: {} additionalProperties: true NotFound: description: Resource not found content: application/vnd.api+json: schema: type: object description: | Error objects provide additional information about problems encountered while performing an operation. Errors also contain codes besides title and message which can be used for checks even if the detailed messages might change. * `1000`: generic error * `1001`: payment processing temporarily unavailable * `1002`: requested amount exceeds the authorized amount of the provided token * `1003`: implicit payment methods cannot be modified * `1004`: payment method rejected by provider * `provider:payment-method-rejected`: payment method rejected by provider (identical to `1004`) * `rule:product-denied`: Product restrictions forbid transaction, e.g., forbidden fuel type - token authorized only for Diesel but attempted to fuel Super. properties: errors: type: array items: type: object properties: id: type: string description: A unique identifier for this particular occurrence of the problem. links: type: object properties: about: type: string description: 'A link that leads to further details about this particular occurrence of the problem. ' status: type: string description: 'the HTTP status code applicable to this problem, expressed as a string value. ' code: type: string description: 'an application-specific error code, expressed as a string value. ' title: type: string description: 'A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. ' detail: type: string description: 'a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. ' source: type: object description: 'An object containing references to the source of the error. ' properties: pointer: type: string description: 'A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. ' parameter: type: string description: 'A string indicating which URI query parameter caused the error. ' meta: type: object description: 'a meta object containing non-standard meta-information about the error. ' properties: {} additionalProperties: true UnsupportedMediaType: description: The specified content type header is invalid content: application/vnd.api+json: schema: type: object description: | Error objects provide additional information about problems encountered while performing an operation. Errors also contain codes besides title and message which can be used for checks even if the detailed messages might change. * `1000`: generic error * `1001`: payment processing temporarily unavailable * `1002`: requested amount exceeds the authorized amount of the provided token * `1003`: implicit payment methods cannot be modified * `1004`: payment method rejected by provider * `provider:payment-method-rejected`: payment method rejected by provider (identical to `1004`) * `rule:product-denied`: Product restrictions forbid transaction, e.g., forbidden fuel type - token authorized only for Diesel but attempted to fuel Super. properties: errors: type: array items: type: object properties: id: type: string description: A unique identifier for this particular occurrence of the problem. links: type: object properties: about: type: string description: 'A link that leads to further details about this particular occurrence of the problem. ' status: type: string description: 'the HTTP status code applicable to this problem, expressed as a string value. ' code: type: string description: 'an application-specific error code, expressed as a string value. ' title: type: string description: 'A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. ' detail: type: string description: 'a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. ' source: type: object description: 'An object containing references to the source of the error. ' properties: pointer: type: string description: 'A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. ' parameter: type: string description: 'A string indicating which URI query parameter caused the error. ' meta: type: object description: 'a meta object containing non-standard meta-information about the error. ' properties: {} additionalProperties: true Conflict: description: Resource conflicts content: application/vnd.api+json: schema: type: object description: | Error objects provide additional information about problems encountered while performing an operation. Errors also contain codes besides title and message which can be used for checks even if the detailed messages might change. * `1000`: generic error * `1001`: payment processing temporarily unavailable * `1002`: requested amount exceeds the authorized amount of the provided token * `1003`: implicit payment methods cannot be modified * `1004`: payment method rejected by provider * `provider:payment-method-rejected`: payment method rejected by provider (identical to `1004`) * `rule:product-denied`: Product restrictions forbid transaction, e.g., forbidden fuel type - token authorized only for Diesel but attempted to fuel Super. properties: errors: type: array items: type: object properties: id: type: string description: A unique identifier for this particular occurrence of the problem. links: type: object properties: about: type: string description: 'A link that leads to further details about this particular occurrence of the problem. ' status: type: string description: 'the HTTP status code applicable to this problem, expressed as a string value. ' code: type: string description: 'an application-specific error code, expressed as a string value. ' title: type: string description: 'A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. ' detail: type: string description: 'a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. ' source: type: object description: 'An object containing references to the source of the error. ' properties: pointer: type: string description: 'A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. ' parameter: type: string description: 'A string indicating which URI query parameter caused the error. ' meta: type: object description: 'a meta object containing non-standard meta-information about the error. ' properties: {} additionalProperties: true TooManyRequests: description: 'Your resource creation limit is exceeded ' content: application/vnd.api+json: schema: type: object description: | Error objects provide additional information about problems encountered while performing an operation. Errors also contain codes besides title and message which can be used for checks even if the detailed messages might change. * `1000`: generic error * `1001`: payment processing temporarily unavailable * `1002`: requested amount exceeds the authorized amount of the provided token * `1003`: implicit payment methods cannot be modified * `1004`: payment method rejected by provider * `provider:payment-method-rejected`: payment method rejected by provider (identical to `1004`) * `rule:product-denied`: Product restrictions forbid transaction, e.g., forbidden fuel type - token authorized only for Diesel but attempted to fuel Super. properties: errors: type: array items: type: object properties: id: type: string description: A unique identifier for this particular occurrence of the problem. links: type: object properties: about: type: string description: 'A link that leads to further details about this particular occurrence of the problem. ' status: type: string description: 'the HTTP status code applicable to this problem, expressed as a string value. ' code: type: string description: 'an application-specific error code, expressed as a string value. ' title: type: string description: 'A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. ' detail: type: string description: 'a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. ' source: type: object description: 'An object containing references to the source of the error. ' properties: pointer: type: string description: 'A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. ' parameter: type: string description: 'A string indicating which URI query parameter caused the error. ' meta: type: object description: 'a meta object containing non-standard meta-information about the error. ' properties: {} additionalProperties: true securitySchemes: OIDC: type: openIdConnect openIdConnectUrl: https://id.pace.cloud/auth/realms/pace/.well-known/openid-configuration OAuth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://id.pace.cloud/auth/realms/pace/protocol/openid-connect/auth tokenUrl: https://id.pace.cloud/auth/realms/pace/protocol/openid-connect/token refreshUrl: https://id.pace.cloud/auth/realms/pace/protocol/openid-connect/token scopes: user:device-totps:create: Create Device totp user:device-totps:create-after-login: Create Device totp within 5 minutes of user registration user:otp:create: Create OTP user:otp:verify: Verify OTP user:callbacks:password-reset: Callback before password is reset user:terms:accept: Accept terms of service user:users.password:check: Check if user password is set user:users.password:create: Add user password user:users.phone:check: Check if user phone is set user:users.phone:update: Change the user phone number user:users.pin:check: Check if user PIN is set user:users.pin:update: Update PIN user:users:delete: Deletes a user user:users:read: Read user data user:users:write: Update user data user:user:delete: Deletes the account of the current user user:sessions:update: Update the current user session user:preferences:read: Get the users app preferences user:preferences:write: Update the users app preferences