The SDKs authenticate with an API token that you create in the dashboard. This page explains which token to use and how the SDKs send it.
Which token to use
| Scenario | Token |
|---|---|
| Your server reads documents and renders them | An application token (scope documents:read is enough) |
| Your server also reads sites, resources or account data | An application token with sites:read, resources:read or organization:read as needed |
| A browser iframe must open a document that requires an access token | A document token for that document |
See API tokens to create them. Never put an application token in code that runs in the visitor's browser.
How the SDKs send the token
getDocument() calls GET https://dash.legalcloud.info/d/{hash}?lang={lang}; the other methods call https://api.legalcloud.info/api/.... All of them send these headers:
| Header | Value |
|---|---|
Authorization | Bearer <token> |
X-LegalCloud-Source | The integration source you configure (custom, drupal, magento, prestashop, shopify…) |
X-LegalCloud-Site | The URL of your website |
X-LegalCloud-Plugin-Id | A unique id of your installation (generated automatically if you do not pass one) |
X-LegalCloud-Version | The version of your integration |
iframeHtml() builds an iframe whose address contains the token as ?token=…, because a browser iframe cannot send headers. Use a document token for this case: it can only open that one document, so a leaked iframe address exposes nothing else. The token appears in server logs and in the browser history, which is why an application token must never be used here.
Configuration
| Option | Required | Description |
|---|---|---|
| token | yes | Your API token |
| source | yes (JS: recommended) | Source name for analytics |
| site URL | yes (JS: optional) | The URL of the website that embeds the document |
| plugin id | no | Unique id of the installation; generated if omitted. Keep it stable between requests |
| version | no | Version of your integration (default: the SDK version) |
| base URL | no | API origin, default https://api.legalcloud.info |
| embed base URL | no | Origin of the public /d/{hash} pages, default https://dash.legalcloud.info |
Error handling
If the document does not exist, is not published, the visitor's country or your site is not allowed, the scope is missing or the token is wrong, LegalCloud answers with an HTTP error (401, 403, 404, 429; see Errors reference). Every SDK maps the status to a specific error class: AuthenticationError (401), PermissionDeniedError (403, with the code SCOPE_FORBIDDEN or PLAN_UPGRADE_REQUIRED), NotFoundError (404), ValidationError (400 / 422), RateLimitError (429, with the seconds to wait and the quota headers) and ServerError (5xx). They share a base class (LegalCloudError in JavaScript and Python, LegalCloudException in PHP), so one catch handles all of them. 429 and 5xx are retried automatically first.