verifyOAuthToken

This API call is used to log into Erply API using signed tokens. This call is used for single sign-on integration, we accept user data containing token for logging into Erply, this token will be validated using public key server.

If required configuration is missing or contains incorrect format errors 1187 or 1188 will be returned, configuration data can be set using setOAuthConfiguration call.

If token parsing failed error 1191 will be returned.

If token doesnt contain required information error 1172 will be returned.

If no user exist to match with provided data error 1173 will be returned, user can be created from same tokens using createUserFromOAuthToken call.

If user "roles" cannot be matched with any Erply user group error 1059 will be returned, token can change or assign user group according to mapping stored in configuration, see setOAuthConfiguration call.

Here is the intended use case explained in more detail.

Input parameters

Parameter name Description Possible value Required
idToken Json Web Token containing user data, required fields - "mail", "roles" - set of user roles, optionally - "givenName" and "familyName". string yes
expiresIn Session length in seconds. integer yes

Response

Field name Type Description
userID integer ID of the user account
userName string The same username that was passed as input
employeeID integer ID of the company employee that has the abovementioned user account
employeeName string
groupID integer ID of the user group where the user belongs
groupName string name of the user group
ipAddress string IP address of the API client.
sessionKey string session identifier, to be used for subsequent API calls.
sessionLength integer time after which the session key expires (in seconds).
loginUrl string URL from where user can log into Erply backend, through web browser.

This URL does not affect API usage and should not be used for sending API calls.
berlinPOSVersion string Application-specific field for Erply's Berlin POS. Indicates the version number (typically an integer) of the live / production POS version that is appropriate for this customer — or the version that has specifically been configured for this customer.

This field does not mean that the customer is definitely using Berlin POS. The customer may be using other POS products or not using a POS at all.

Also, API does not currently provide a POS version number for preproduction / staging / testing.
berlinPOSAssetsURL string Application-specific field for Erply's Berlin POS. Indicates the URL from where POS can load its static assets.

The URL does not include and does not depend on POS version number. POS should append version number to the URL, or perform some other transformation if needed.
epsiURL string Application-specific field for Erply's Berlin POS. Indicates the location of the JNLP file for Erply Point Of Sale Integrator (EPSI), which provides support for various POS hardware.
cayanGatewayURLs array

Application-specific field for Berlin POS - returned only for Berlin POS.

List of Cayan (Merchant Warehouse) payment gateway URLs for this particular account. This only specifies the most appropriate service endpoints for the account to use; it does not indicate that the account is actually using Cayan payment integration.

This array may contain 0 or more records. If Cayan support has been disabled in this server, the array will be empty. Otherwise it will contain at least one record.

Each record in the array contains the following fields:

Field nameTypeDescription
targetStringService hostname
portIntegerService port
weightInteger (0..65535)For load balancing. See internal documentation.
priorityInteger (0..65535)Priority of this host. See internal documentation.
avalaraGatewayURLs array

Application-specific field for Berlin POS - returned only for Berlin POS.

URLs of gateways to the Avalara tax calculation service. This only specifies the most appropriate service endpoints to use, if needed, and does not indicate that the account is actually using Avalara integration.

This array may contain 0 or more records. If Avalara support has been disabled in this server, the array will be empty. Otherwise it will contain at least one record.

Each record in the array contains the following fields:

Field nameTypeDescription
targetStringService hostname
portIntegerService port
weightInteger (0..65535)For load balancing. See internal documentation.
priorityInteger (0..65535)Priority of this host. See internal documentation.
pusherAuthenticationURLs array

Application-specific field for Berlin POS - returned only for Berlin POS.

URLs of gateways to the Pusher messaging service, for this particular account.

This array may contain 0 or more records. If Pusher support has been disabled in this server, the array will be empty. Otherwise it will contain at least one record.

Each record in the array contains the following fields:

Field nameTypeDescription
targetStringService hostname
portIntegerService port
weightInteger (0..65535)For load balancing. See internal documentation.
priorityInteger (0..65535)Priority of this host. See internal documentation.
strikeIronGatewayURLs array

Application-specific field for Berlin POS - returned only for Berlin POS.

URLs of gateways to the StrikeIron (Informatica) tax rate lookup service, for this particular account.

This array may contain 0 or more records. If StrikeIron support has been disabled in this server, the array will be empty. Otherwise it will contain at least one record.

Each record in the array contains the following fields:

Field nameTypeDescription
targetStringService hostname
portIntegerService port
weightInteger (0..65535)For load balancing. See internal documentation.
priorityInteger (0..65535)Priority of this host. See internal documentation.
customerRegistryURLs array

Information about standalone customer registry service.

This array may contain 0 or more records. If account does not use a standalone customer registry (customers are stored in Erply as usual), this list will be empty. Otherwise it will contain at least one record.

Each record in the array contains the following fields:

Field nameTypeDescription
urlStringURL of the service endpoint (with "https://" protocol in the beginning and "/" in the end). Append the names of API calls (eg. "V1/Customer/create") to this URL.
tokenIntegerAuthentication token for the service. When the customer service reports the token has expired, call verifyOAuthToken or verifyUser again to get a new one.
priorityInteger (0..65535)Priority of this host. A client must attempt to contact the target host with the lowest-numbered priority it can reach. Target hosts with the same priority should be tried in pseudorandom order.
weightInteger (0..65535)For load balancing. When selecting a target host among those that have the same priority, the chance of trying this one first should be proportional to its weight. Larger weights SHOULD be given a proportionately higher probability of being selected.
couponRegistryURLs array

Information about standalone coupon registry service.

This array may contain 0 or more records. If account does not use a standalone coupon registry (coupons are stored in Erply as usual), this list will be empty. Otherwise it will contain at least one record.

Each record in the array contains the following fields:

Field nameTypeDescription
urlStringURL of the service endpoint (with "https://" protocol in the beginning and "/" in the end). Append the names of API calls to this URL.
tokenIntegerAuthentication token for the service. When the coupon service reports the token has expired, call verifyOAuthToken or verifyUser again to get a new one.
priorityInteger (0..65535)Priority of this host. A client must attempt to contact the target host with the lowest-numbered priority it can reach. Target hosts with the same priority should be tried in pseudorandom order.
weightInteger (0..65535)For load balancing. When selecting a target host among those that have the same priority, the chance of trying this one first should be proportional to its weight. Larger weights SHOULD be given a proportionately higher probability of being selected.
transactionRegistryURLs array

Information about standalone transaction registry service.

This array may contain 0 or more records. If account does not use a standalone transaction registry (transactions are stored in Erply as usual), this list will be empty. Otherwise it will contain at least one record.

Each record in the array contains the following fields:

Field nameTypeDescription
urlStringURL of the service endpoint (with "https://" protocol in the beginning and "/" in the end). Append the names of API calls to this URL.
tokenIntegerAuthentication token for the service. When the transaction service reports the token has expired, call verifyOAuthToken or verifyUser again to get a new one.
priorityInteger (0..65535)Priority of this host. A client must attempt to contact the target host with the lowest-numbered priority it can reach. Target hosts with the same priority should be tried in pseudorandom order.
weightInteger (0..65535)For load balancing. When selecting a target host among those that have the same priority, the chance of trying this one first should be proportional to its weight. Larger weights SHOULD be given a proportionately higher probability of being selected.
displayAdManagerURLs array

Information about the service that provides advertisements to the point-of-sale customer display screen. (This information is meant for Berlin POS.)

This array may contain 0 or more records. If account has not been configured to use the advertisement manager, this list will be empty. Otherwise it will contain at least one record.

Each record in the array contains the following fields:

Field nameTypeDescription
urlStringURL of the service endpoint (with "https://" protocol in the beginning and "/" in the end). Append the names of API calls to this URL.
tokenIntegerAuthentication token for the service.
priorityInteger (0..65535)Priority of this host. A client must attempt to contact the target host with the lowest-numbered priority it can reach. Target hosts with the same priority should be tried in pseudorandom order.
weightInteger (0..65535)For load balancing. When selecting a target host among those that have the same priority, the chance of trying this one first should be proportional to its weight. Larger weights SHOULD be given a proportionately higher probability of being selected.
epsiDownloadURLs array

Provides URLs with downloadable packages for EPSI (Erply point of sale integrator) installation. Provides a record per each operating system with installation link.

Each record in the array contains the following fields:

Field nameTypeDescription
operatingSystemStringPossible values - "Windows", "macOS" and "Linux"
urlStringInstallation link
identityToken string

Provides Identity API Json Web Token

Can be used with integrations that require the JWT for authentication. This can also be retrieved with getIdentityToken with a session key without username and password.

token string

Replaces identityToken. Provides an Erply generated JWT token.

Can be used with integrations that require the JWT for authentication. This can also be retrieved with getJwtToken with a session key without username and password.