---
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-2
servers:
- url: https://api.pace.cloud/user/2024-2
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"
"/terms/update":
put:
tags:
- Terms
operationId: UpdateTerms
security:
- OAuth2:
- user:terms:update
- OIDC:
- user:terms:update
summary: Update the terms cache
description: Triggers an update to the terms cache.
responses:
'204':
description: terms successfully updated
'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.
html:
type: string
description: Terms of service formatted as HTML
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