Introduction to XDOC API Services


Please start by reading this introductory page and following sections for the API services you are interested in.

After you have done your initial review of the documentation, we can setup an API Introductory Call with your developer(s).


General Overview

XDOC provides the following API services:


Configuring the XDOC API Settings in the User Interface

The XDOC API Settings for a project can be found under Admin > 'Projects' Tab > HTTP Server Service & UI Launch Service in the side menu:



Please note these settings are relative to each project; the Project Id must be specified in request URLs using the ProjectId parameter.

The Project Id is found on the Admin > 'Projects' Tab > Project Info > Project Definition page. The default Project Id is 1000.


Security Considerations

Access to the XDOC API Services is restricted by the Remote Ip Acl List defined on the Project API Settings page. For an extra layer of security, a Security Context (XSC parameter) and a Security Token (XST parameter) can also be included when making requests.

The Securty Context is defined on the Project API Settings page and can be set as required. If the Security Context is defined and set to be required, it must be included in requests by input to the XSC parameter.

The encryption/decryption settings for the Security Token are also defined on the Project API Settings page. The Securty Token can also be set as required. If the Security Token is set to be required, it must be included in requests by input to the XST parameter.

For more information please see S4. Security Token Authentication and S4. Security Considerations pages.


Constructing Request URLs

The domain for the XDOC Server will be used as the base for all API request URLs.


HTTP Server Services

All HTTP Service Methods are accessible via the /XDocApi/?XM= endpoint with the desired service method specified by input to the XM parameter.

Sample Container.ContainerInfo Invoke URL:

https://xdoc.example.com/XDocApi/?XM=Container.ContainerInfo&ContainerKey=201001&XSC=MySecurityContext&XST=VVp57msUPMDgpqVqEdYN80PWgk8ek85nAasL3E26zUZ1t%2BMweH%2Fw%2BSSXMvkljE13E%2FbiIcu0%2BdXMwRIfEK9fplqH7JqAGOlqhqKmF%2BYVS1htqx8U7ZZZl2hUa4cS4ee9DGUBMPAvsgd4B1nhs%2F7loQ1GmLS0%2F%2BKfWdJGPUg4yiJNL5aQpDT6w7MCPNlNrTLfiHyRjef0A1TlpJ%2BwT0d7mQ%3D%3D

For more information on constructing URLs for invoking HTTP service methods please see S1. Method Invocation Syntax in the HTTP Server Services API section.


User Interface Services

All User Interface Service Links are accessible via the /XDocUi/?AppLink= endpoint with the link type specified by input to the AppLink parameter.

If providing a User Token for user authentication in UI Interface Service requests, it may specified in requests by input to the XUT parameter.

Sample APPDASHBOARD UI Launch URL:

https://xdoc.example.com/XDocUi/?AppLink=APPDASHBOARD&XSC=MySecurityContext&XUT=gWd0ky0DfSFt1wVAYJM4cVWANSkSjQv%2FCi%2BwdLlAh1Cya4i9MM4gMWYneTcbjVyo72QTv3It%2F0GezGRg%2BP2HG50zfUk%2BiGZRyb6VBiMD15A%3D

For more information on constructing Launch URLs please see S1. Service Invocation Syntax in the User Interface Service section.


Generating Tokens

After configuring the encryption settings on the Project API Settings page, the Security and User Tokens may be generated for inclusion in requests. Here is a brief overview:

  1. The tokens are first constructed in plaintext using either XML, JSON, or a form-url string.

    Sample Plaintext XML Security Token:

    <SecurityToken>
        <Context>MySecurityContext</Context>
        <AppId>MyAppId</AppId>
        <AppKey>MyAppKey</AppKey>
        <GenDT>2021-03-08T14:15:53-08:00</GenDT>
    </SecurityToken>


    Sample Plaintext XML User Token:

    <UserToken>
        <UserName>admin</UserName>
        <Display>John Doe</Display>
    </UserToken>


  2. The plaintext tokens must then be encrypted and Base64 encoded in accordance with the standards chosen on the Project API Settings page.

    Sample Security Token Encrypted and Base64 encoded:

    "C15OEgi932oPFmjdi6LH9w94vBOqvrdua4vKA+aAnoHe3E+0s06jIYs/Q5LxY2nC17qcpyCUZtbSJRf/PDx7AeScDnzuyUJDynvlwUJF8ebdHBFUvNWTFw4Oad8gbrmG4tC72zcj9BlBYpJv0DW5PXr4g/hnlEDg8Q8Wh6E1oO/6jLF8Y4FQRUej/LzYzNUnMZ5SLahHV54PdMtjU5VHfsvNuwRrCITJF9gmXmQtFD44wtvbYjAT0GhbXTwHp0XQ"


    Sample User Token Encrypted and Base64 encoded:

    "MkclD3MPKt5gQBcRDoqek5neDQjto+rXc7cneMpPoQV+JqL52gJt4K2e3vOmjf6RCBRrQUjYh4fdzD2qT6iYIrXrEX6OblTTmoxfhpvehOQU6NvEpzOPgkfUl8fMU3TV"


  3. Finally, the tokens must be URL encoded for use in API request URLs.

    URL Encoded Security Token Passed to the XST parameter:

    "C15OEgi932oPFmjdi6LH9w94vBOqvrdua4vKA%2BaAnoHe3E%2B0s06jIYs%2FQ5LxY2nC17qcpyCUZtbSJRf%2FPDx7AeScDnzuyUJDynvlwUJF8ebdHBFUvNWTFw4Oad8gbrmG4tC72zcj9BlBYpJv0DW5PXr4g%2FhnlEDg8Q8Wh6E1oO%2F6jLF8Y4FQRUej%2FLzYzNUnMZ5SLahHV54PdMtjU5VHfsvNuwRrCITJF9gmXmQtFD44wtvbYjAT0GhbXTwHp0XQ"


    Final User Token Passed to the XUT parameter:

    "MkclD3MPKt5gQBcRDoqek5neDQjto%2BrXc7cneMpPoQV%2BJqL52gJt4K2e3vOmjf6RCBRrQUjYh4fdzD2qT6iYIrXrEX6OblTTmoxfhpvehOQU6NvEpzOPgkfUl8fMU3TV"


    For more information on Security Token Encryption, please see S4. Security Token Authentication in the HTTP Server Services API section.

    For more information on use of the User Token please see S3. User Token Credential Passing in the User Interface Service section.


Troubleshooting Common Errors

Returned in XML Response's ErrorInfo/ResultInfo Solution
SecurityValidateFailed Please check that the remote client application's IP address is added to the Remote Ip Acl List on the Project API Settings page.
SecurityCtxMissing Please check that you are passing a value to the XSC parameter or set Require Security Context to 'no' on the Project API Settings page.
SecurityCtxInvalid Please check that you are passing the correct security context value (as defined in the Project API Settings page) to the XSC parameter. Also check that your are passing the correct Project Id to the ProjectId parameter.
SecurityTokenMismatchCtx Please check that the Security Context defined in Security Token matches the value being passed to the XSC parameter.
SecurityTokenMissing Please check that you are passing a value to the XST parameter or set Require Security Token to 'no' on the Project API Settings page.
SecurityTokenDecryptionFailed Please check that you using the same encryption standards and padding to encrypt the Security Token as defined in the Project API Settings page. You may use the encryption/decryption utility found in Admin > 'Utils' Tab > String Encryptor/Decryptor to verify your tokens are encrypted correctly.
SecurityTokenMissingAppId Please check that you are defining an AppId in your token.
SecurityTokenInvalidAppKey Please check that you are defining an AppKey in your token and that it is included in the Security Token App Keys list defined in the API settings page.
SecurityTokenExpired Please generate a new Security Token or increase the Token Expire Time (Sec) defined in the Project API Settings page.