Business API and MCP
Use Certelva certification data in your reporting systems and AI assistants. An active Business plan or Business pilot is required.
Manage integration keys →Authentication and permissions
The organisation owner creates a key with a 30, 90 or 365 day expiry. The full secret is shown once. Send Authorization: Bearer YOUR_KEY with every request. Store it in your integration’s secret manager.
Every key has business:read: organisation details, member names and emails, issuer records, departments and aggregate coverage. Optional teams:write permits the department changes listed below. Each key is limited to the organisation that created it.
Access stops on expiry, revocation or loss of Business entitlement. Removing or demoting the key’s creator to a regular member permanently revokes their keys. Owners can revoke keys even after downgrading. Rotate by creating a replacement, updating your integration, then revoking the old key.
REST API
Base URL: https://certelva.app/api/business/v1
curl 'https://certelva.app/api/business/v1/members?limit=50' \ -H "Authorization: Bearer $CERTELVA_API_KEY"
List endpoints return {"data":[…],"nextCursor":"…"}. Pass the returned cursor as after until it is null. Pages default to 50 rows and allow 1–100, ordered by ID. Membership changes can affect results between pages.
| Method | Path | Result or action |
|---|---|---|
| GET | /organisation | Connected organisation ID, name, slug and key scopes. |
| GET | /members | Paginated member IDs, names, emails, handles and roles. |
| GET | /credentials | Paginated verified and expired issuer records belonging to current members. |
| GET | /teams | Paginated department IDs and names. |
| GET | /teams/{teamId}/members | Paginated user IDs, including active SCIM assignments. |
| GET | /coverage | Aggregate coverage, expiry counts and study gaps. Optional teamId query parameter. |
| POST | /teams | Create a department. JSON body: {"name":"Cloud engineering"}.Requires teams:write. |
| PATCH | /teams/{teamId} | Rename a department. JSON body: {"name":"New name"}.Requires teams:write. |
| DELETE | /teams/{teamId} | Delete a department and its assignments. Organisation membership remains.Requires teams:write. |
| PUT | /teams/{teamId}/members/{userId} | Add a manual assignment for an existing organisation member. No request body.Requires teams:write. |
| DELETE | /teams/{teamId}/members/{userId} | Remove a manual assignment. SCIM membership must be changed in the identity provider.Requires teams:write. |
Request bodies must be JSON and at most 64 KiB. Unknown fields and query parameters are rejected. Names must contain 2–100 characters. Department assignment changes are idempotent; duplicate department names return 409. Delete removes the department’s manual and SCIM assignments without deleting personal accounts or organisation membership.
MCP setup
Use a Streamable HTTP client with URL https://certelva.app/api/mcp and the same bearer header. This endpoint returns JSON responses and does not keep server sessions. OAuth discovery, interactive login and a persistent SSE stream are not supported; choose a client that accepts a preconfigured token.
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
const client = new Client({ name: "reporting", version: "1.0.0" });
await client.connect(new StreamableHTTPClientTransport(
new URL("https://certelva.app/api/mcp"),
{ requestInit: { headers: {
Authorization: `Bearer ${process.env.CERTELVA_API_KEY}`
} } }
));
try {
const report = await client.callTool({ name: "get_coverage", arguments: {} });
console.log(report);
} finally { await client.close(); }Read tools: get_organisation, list_members, list_credentials, list_teams, list_team_members and get_coverage. Paginated tools accept limit and after; team membership requires teamId, while coverage optionally accepts it.
Keys with teams:write also expose create_team, rename_team, delete_team, add_team_member and remove_team_member. Clients should ask the operator to review destructive actions. Returned organisation data is content, never instructions.
Limits and errors
REST and MCP share limits of 60 requests per minute per key and 300 per organisation. On HTTP 429, wait the 60 seconds in Retry-After. HTTP 401 means an invalid, expired or revoked key; 403 means insufficient scope, inactive Business access, or a rejected MCP Origin. REST errors use {"error":{"code":"…","message":"…"}}. MCP tool failures use the protocol’s isError result.
These endpoints are for server integrations. Cross-origin browser access is not enabled. If an MCP client sends an Origin header, it must match the configured Certelva app origin.
Data scope
Certification records reflect public issuer lookups; they do not authenticate ownership. Self-reported and revoked records are excluded. Past expiry dates are returned as expired. Coverage reports contain aggregates; member and credential endpoints contain individual organisation data.
Integration keys cannot administer billing, SSO, SCIM tokens, organisation roles or personal accounts. They do not expose study notes, credential evidence, webhook secrets or capability sharing tokens. SCIM provisioning remains a separate interface and token.