API reference

Every endpoint a client application, the CLI or the SDK calls, with how each one is authenticated.

Base address#

Every path below is relative to your VERISCO platform's address, written https://your-verisco-host in the examples. Responses are JSON unless stated. An error is a JSON object with a detail or an error field and an HTTP status that means what it says.

Authentication#

Three schemes, each for a different caller.

Scheme	Who uses it	How
None	Anyone	Endpoints that carry no tenant value: the contract, the package downloads.
Analyzer key	The CLI, your pipeline	`Authorization: Bearer <analyzer key>`. The key is on your integration page in the console.
Client credentials	The SDK, in SDK mode	HTTP Basic with your client id (`<tenant-id>-user`) and client secret.

Keep both secrets out of your repository

The analyzer key can read your integration guide and turn protection on or off. The client secret completes sign-ins as your application. Store them in your environment or your secret manager.

Integration#

GET/api/v1/contract

The machine-readable integration contract: the cookie and header names, the signing algorithm, the claims, the package names, the supported frameworks and the code to paste.

Authentication: none. It contains no tenant value.

Shell

curl -fsS https://your-verisco-host/api/v1/contract

JSON

{
  "contract_version": "1.0",
  "transport": {
    "session_cookie": "verisco_session",
    "claims_header": "X-Verisco-Claims",
    "user_header": "X-Verisco-User",
    "verified_header": "X-Verisco-Verified",
    "algorithm": "RS256"
  },
  "public_key": { "path": "/api/v1/public-key", "filename": "verisco_public.pem" },
  "packages": { "cli_binary": "verisco-analyzer" },
  "frameworks": {},
  "snippets": {}
}

GET/api/v1/public-key

Your tenant's RS256 public key, as a PEM file.

Authentication: the analyzer key, as the api_key query parameter.

Status	Meaning
`200`	The key, `application/x-pem-file`.
`401`	The key is not valid.
`404`	No signing key yet. The tenant has not been published.

Shell

curl -fsS "https://your-verisco-host/api/v1/public-key?api_key=$VERISCO_ANALYZER_KEY" -o verisco_public.pem

GET/tenants/{tenant_id}/public-key

Every public key your application should currently accept. During a key rotation that is two: the one in use and the one about to be. An application that fetches this while a key is staged is ready before anything changes.

Authentication: none. A public key is public.

GET/api/v1/sdk/node

The Node middleware, as a tarball that npm installs directly.

Authentication: none.

Shell

npm install https://your-verisco-host/api/v1/sdk/node

GET/api/v1/cli/install

A POSIX shell installer for the CLI. It verifies the download's checksum before installing it.

Authentication: none.

Shell

curl -fsSL https://your-verisco-host/api/v1/cli/install | sh

Analysis#

POST/api/v1/ai-analyze

Asks for an AI-written integration guide for the files sent. Called by verisco-analyzer analyze --use-ai.

Authentication: analyzer key. Rate limit: 5 requests per hour, per tenant.

Field	Type	Meaning
`files`	object	File path to file content, for the authentication-related files.
`package_json`	object	Optional. Your project's `package.json`.

The guide is saved to your tenant and shown on your integration page.

GET/api/v1/guide

The stored guide's edits, in the form verisco-analyzer apply writes them.

Authentication: the analyzer key, as the api_key query parameter.