Seclore Online Integration – Developer Guide

1. Introduction

This guide covers the technical implementation for integrating an Enterprise Application with Seclore Online — including key concepts, communication flows, security (proof keys), API specifications, and design considerations. It is intended for technical architects and development teams.

Readers are expected to have hands-on knowledge of RESTful web services and JSON, and an understanding of how files move in and out of the enterprise application being integrated.

2. Implementation Details

2.1 Key Concepts

File Token

A File Token is a unique string that represents a specific file in the enterprise application. Seclore Online includes the file token in all requests back to the enterprise application, allowing the host to locate the file.

A File Token must represent a single file and be URL-safe (tokens are passed in URLs).

Access Token

A string used by the enterprise application to determine the identity and permissions of the issuer of a request. The enterprise application provides an access token; Seclore Online passes it back on subsequent requests for validation.

Access tokens must:

• Be scoped to a single user and resource combination.
• Remain valid for all operations the user has permissions to perform (a view token stays valid when switching to edit mode).
• Expire automatically — use access_token_ttl to specify expiry.
• Only be revoked if a user's permissions change, not as a standard operation.

Access Token TTL

The access_token_ttl property specifies when an access token expires, expressed as milliseconds since January 1, 1970 UTC — an absolute timestamp, not a duration. It is always paired with a specific access token.

File Hash

During file opening, Seclore Online stores the file contents and its hash. If a subsequent open request arrives with the same hash, Seclore Online reuses the cached contents instead of calling getFile again.

Session Context

A property the enterprise application generates to store session-related data. Once sent to Seclore Online, this data is echoed back in all subsequent requests.

Cloud File Access on Desktop (CFAD)

Seclore Online can open files natively using the Seclore Desktop Client on the user's machine. After editing, the file is saved back to the enterprise application. Technical details are in Section 5.3.

Discovery

The process by which an enterprise application obtains proof keys, supported versions, and features from Seclore Online. Cache the discovery response and refresh it every 12–24 hours, or re-run it when proof key validation fails (indicating keys may have been rotated).

2.2 Communication Flows

Solid arrows = requests  ·  Dashed arrows = responses

Flow A — File Open in View Mode, Switched to Edit

Flow B — File Open with Save-back

Flow C — File Open via CFAD (Cloud File Access on Desktop)

2.3 Integrity & Proof Keys

Discovering Proof Keys

The Discovery endpoint returns proof keys used to sign and verify all requests between Seclore Online and the enterprise application. Cache the response and refresh every 12–24 hours, or re-run discovery when proof key validation fails.

Proof Validation and Rollover

Seclore Online signs every request with a private key. The corresponding public key is in the proof-key field of the discovery response, sent via X-Seclore-Proof and X-Seclore-ProofOld HTTP headers.

To verify a request, check these three combinations in order — if any one passes, the request is authentic:

• X-Seclore-Proof decrypted with the current public key
• X-Seclore-ProofOld decrypted with the current public key
• X-Seclore-Proof decrypted with the old public key

If none of the three passes, return 500 Internal Server Error.

Building the expected proof (Java):

private static byte[] getExpectedProofBytes(String pUrl, String pAccessToken, String pTimestamp) {
    final byte[] accessTokenBytes = pAccessToken.getBytes(StandardCharsets.UTF_8);
    final byte[] hostUrlBytes = pUrl.toUpperCase().getBytes(StandardCharsets.UTF_8);
    final Long timestamp = Long.valueOf(pTimestamp);
    final ByteBuffer byteBuffer = ByteBuffer.allocate(
        4 + accessTokenBytes.length + 4 + hostUrlBytes.length + 4 + 8);
    byteBuffer.putInt(accessTokenBytes.length);
    byteBuffer.put(accessTokenBytes);
    byteBuffer.putInt(hostUrlBytes.length);
    byteBuffer.put(hostUrlBytes);
    byteBuffer.putInt(8);
    byteBuffer.putLong(timestamp);
    return byteBuffer.array();
}

Verifying the proof (Java):

public static boolean verifyProofKey(String strModulus, String strExponent,
        String strProofKey, byte[] expectedProofArray) throws Exception {
    PublicKey publicKey = getPublicKey(strModulus, strExponent);
    Signature verifier = Signature.getInstance("SHA256withRSA");
    verifier.initVerify(publicKey);
    verifier.update(expectedProofArray);
    final byte[] signedProof = DatatypeConverter.parseBase64Binary(strProofKey);
    return verifier.verify(signedProof);
}

Renew Access Token

When an access token expires, the enterprise application must return 401. Seclore Online then calls the Renew Access Token endpoint with the expired token. The enterprise application validates it and returns a new token, which Seclore Online uses to retry the failed request.

3. Configurations

Whitelist Enterprise Application URL in Seclore Online

To open protected files using Seclore Online, the enterprise application URL must be whitelisted. Without this, Seclore Online will reject all requests from the application. One Seclore Online instance supports multiple whitelisted applications.

Configure the URL following the Seclore Online Installation Manual, then restart Seclore Online for changes to take effect.

4. Design Considerations

Failed Access Token Renewal

If an access token has expired, return 401. Seclore Online calls Renew Access Token with the expired token, and the enterprise application should respond with a new token. Seclore Online retries the original request using the renewed token.

Error URL Framework

Seclore Online returns an error-url in the response header for any exception. The integrating application can redirect to this URL to display contextual Seclore Online error pages (e.g. "file too large to open online", "unsupported extension"), or render a custom error page instead. See Section 5.2 for technical details.

Version Conflict Resolution

When multiple users attempt to edit and save the same file simultaneously, the enterprise application must handle version conflicts. Possible strategies:

• Once a file is open in edit mode, open it in view mode for all other users.
• Allow simultaneous edits, then create a new file on close and let users resolve conflicts manually.

5. APIs & Technical Details

Headers repeated across most APIs are documented in the Header Appendix.

5.1 Seclore Online Endpoints

Prefix the Seclore Online base URL to the paths below.

{
  "proof-keys": {
    "old": { "proof-key": { "modulus": "<BASE64>", "exponent": "<BASE64>", "algo": "SHA256withRSA" } },
    "new": { "proof-key": { "modulus": "<BASE64>", "exponent": "<BASE64>", "algo": "SHA256withRSA" } }
  },
  "versions": [1.0],
  "supported-features": [1.0]
}

{ "allowed-action": [ "view" | "edit" ] }

5.2 Seclore Online Error Framework

5.3 Enterprise Application Endpoints

Implement these endpoints in your enterprise application. Prefix the service URL to the paths below.

{
  "file-name": "string",
  "file-hash": "string",
  "file-hash-algo": "string",
  "file-size": "string",
  "options": {
    "allow-edit": boolean,
    "allow-download": boolean,
    "allow-unprotected-download": 0 | 1,
    "email-copy": boolean,
    "allow-saveback": boolean
  },
  "allowed-action": [ "view" | "edit" ]
}

{ "access-token": "string", "access-token-ttl": 1680000000000 }

{ "actual-allowed-action": "view" | "edit" }

{ "mode": "manual" | "automatic" }

5.4 Status Code Appendix

5.5 Header Appendix

6. FAQs

General integration FAQs are on the FAQs page.

How do I configure a new Policy Server URL?

One Seclore Online instance supports multiple Policy Servers. To add one:

1. Configure the PS URL in your enterprise application to send it as a header and parameter in requests wherever expected.
2. Whitelist the PS URL in Seclore Online following the Seclore Online Installation Manual.
3. Restart Seclore Online for changes to take effect.

7. Glossary