# EthicsPortal API and webhooks > Developer documentation for the EthicsPortal REST API and signed webhooks: report metadata and deadlines, whistleblowing channel setup, members, documents, billing links and the audit trail. Report content is never available through the API. An AI assistant can set up EthicsPortal for a person through the MCP server. - API base URL: `https://secure.ethicsportal.eu`. JSON endpoints end in `.json`; document downloads return PDF or DOCX. - Authenticate with `Authorization: Bearer `. A personal token (`ep_pat_`) acts with its user's current role in each organisation. An organisation token (`ep_oat_`) belongs to one organisation. Each operation names the scope it requires and the token types that can call it. - Start with `GET /identity.json` to discover the organisations a token can reach. Follow the `Link: rel="next"` header to page through lists, and send an `Idempotency-Key` header when retrying a POST. - OpenAPI 3.1 schema: https://ethicsportal.eu/openapi.json - MCP server: `https://secure.ethicsportal.eu/mcp`. An AI assistant connects with OAuth after a person approves it, and calls the same operations as tools: https://ethicsportal.eu/developers/mcp.md - To set up EthicsPortal for a person from an AI assistant, including a person with no account, follow https://ethicsportal.eu/.well-known/agent-skills/ethicsportal-setup/SKILL.md - Changes are additive: ignore unknown fields, values and webhook event types. Versioning rules and every change: https://ethicsportal.eu/developers/changelog.md - Every page below is Markdown. Each HTML page also answers `Accept: text/markdown`. - All of these pages in one file: https://ethicsportal.eu/developers/llms-full.txt ## Guides - [EthicsPortal developer documentation](https://ethicsportal.eu/developers.md): Integrate authorised report metadata and deadlines with your systems, and receive signed webhooks. - [Make your first API request](https://ethicsportal.eu/developers/quickstart.md): Create a token and retrieve authorised report metadata with curl. - [Authentication and permissions](https://ethicsportal.eu/developers/authentication.md): Choose between personal and organisation API tokens, set their scopes, and understand expiry, revocation and case permissions. - [Set up organisations and whistleblowing channels](https://ethicsportal.eu/developers/organisation-setup.md): Create an organisation with a personal token and configure its whistleblowing channel with a personal or organisation token. - [Data boundaries](https://ethicsportal.eu/developers/data-boundaries.md): Which operational fields the API exposes and which confidential report fields are always excluded. - [Pagination, filters and errors](https://ethicsportal.eu/developers/pagination-and-errors.md): Traverse API lists, filter reports, retry safely, handle errors and respect rate limits. - [Webhooks](https://ethicsportal.eu/developers/webhooks.md): Configure signed operational events, verify deliveries and reconcile missed updates. - [Audit trail, members, documents, billing and feedback](https://ethicsportal.eu/developers/administration.md): Read the audit trail into a log collector, manage members and invitations, download documents, read billing status, rename the organisation and send product feedback. - [MCP server for AI assistants](https://ethicsportal.eu/developers/mcp.md): Connect an AI assistant to EthicsPortal through the MCP server. How to add it to an assistant, the OAuth connection, scopes, tools, data boundary and errors. - [SAML and SCIM](https://ethicsportal.eu/developers/identity-integrations.md): Connect Okta, Microsoft Entra ID, Google Workspace or another identity provider to EthicsPortal with SAML 2.0 single sign-on and SCIM 2.0 provisioning. Values to enter, attribute mapping, domain verification, enforcement, endpoints, errors and troubleshooting. ## API reference - [API reference](https://ethicsportal.eu/developers/api.md): Reference for the EthicsPortal metadata API: endpoints, parameters, response schemas, errors and the webhook event payload. - [Discover organisations](https://ethicsportal.eu/developers/api/operations/getidentity.md): Return the organisations that an access token can read, with the token's scopes and expiry date. - [Read whistleblowing channel metadata](https://ethicsportal.eu/developers/api/operations/getchannel.md): Return the whistleblowing channel of one organisation: its ID, whether it is active and the URL of its online reporting form. - [List report metadata](https://ethicsportal.eu/developers/api/operations/listreports.md): List report metadata for one organisation: status, assignment, deadlines and overdue flags. - [Read report metadata](https://ethicsportal.eu/developers/api/operations/getreport.md): Read the metadata of one report: status, assignment, acknowledgement and feedback deadlines, and overdue flags. - [Create an organisation](https://ethicsportal.eu/developers/api/operations/createorganization.md): Create an organisation. - [Read channel configuration](https://ethicsportal.eu/developers/api/operations/getchannelconfiguration.md): Read the channel's company details, settings and compliance officer. - [Configure a whistleblowing channel](https://ethicsportal.eu/developers/api/operations/updatechannelconfiguration.md): Change the channel's company details and settings. - [List webhooks](https://ethicsportal.eu/developers/api/operations/listwebhooks.md): List the organisation's webhooks. - [Create a webhook](https://ethicsportal.eu/developers/api/operations/createwebhook.md): Register a public HTTPS destination for the selected events. - [Read a webhook](https://ethicsportal.eu/developers/api/operations/getwebhook.md): Read one webhook without its secret. - [Delete a webhook](https://ethicsportal.eu/developers/api/operations/deletewebhook.md): Delete the webhook and its delivery history. - [Update a webhook](https://ethicsportal.eu/developers/api/operations/updatewebhook.md): Change the name, URL, enabled state or events; only supplied fields change. - [Rotate a webhook's signing secret](https://ethicsportal.eu/developers/api/operations/rotatewebhooksecret.md): Replace the signing secret immediately; there is no overlap period. - [Send a test event](https://ethicsportal.eu/developers/api/operations/testwebhook.md): Queue a webhook.test event containing only the organisation ID. - [List webhook deliveries](https://ethicsportal.eu/developers/api/operations/listwebhookdeliveries.md): Deliveries retained for 30 days, oldest first. - [Retry a failed delivery](https://ethicsportal.eu/developers/api/operations/retrywebhookdelivery.md): Retry a failed delivery with the webhook's current URL and secret, keeping its event ID. - [List the audit trail](https://ethicsportal.eu/developers/api/operations/listaudittrail.md): The organisation's audit trail: who did what and when. - [List a report's audit trail](https://ethicsportal.eu/developers/api/operations/listreportaudittrail.md): One report's audit trail. - [List members](https://ethicsportal.eu/developers/api/operations/listmembers.md): The organisation's members. - [List pending invitations](https://ethicsportal.eu/developers/api/operations/listinvitations.md): Invitations not yet accepted, declined or expired. - [Invite a member](https://ethicsportal.eu/developers/api/operations/createinvitation.md): Email an invitation that is valid for 14 days. - [Revoke an invitation](https://ethicsportal.eu/developers/api/operations/revokeinvitation.md): Revoke a pending invitation. - [Resend an invitation](https://ethicsportal.eu/developers/api/operations/resendinvitation.md): Send the invitation email again and restart its 14-day validity. - [Rename the organisation](https://ethicsportal.eu/developers/api/operations/updateorganization.md): Change the organisation's name. - [List my invitations](https://ethicsportal.eu/developers/api/operations/listmyinvitations.md): Pending invitations addressed to the token's user. - [Accept an invitation](https://ethicsportal.eu/developers/api/operations/acceptinvitation.md): Join the organisation with the invited role. - [Decline an invitation](https://ethicsportal.eu/developers/api/operations/declineinvitation.md): Decline a pending invitation. - [List documents](https://ethicsportal.eu/developers/api/operations/listdocuments.md): The documents the token may download, with their download URLs. - [Download the compliance report](https://ethicsportal.eu/developers/api/operations/downloadcompliancereport.md): Evidence of the channel's configuration and handling, for auditors. - [Download the compliance certificate](https://ethicsportal.eu/developers/api/operations/downloadcompliancecertificate.md): Certificate of an active whistleblowing channel. - [Download the whistleblowing policy](https://ethicsportal.eu/developers/api/operations/downloadwhistleblowerpolicy.md): Editable policy for staff, filled with the channel's details. - [Download the privacy notice](https://ethicsportal.eu/developers/api/operations/downloadprivacynotice.md): Editable privacy notice for the whistleblowing channel. - [Download the poster](https://ethicsportal.eu/developers/api/operations/downloadposter.md): Poster with the online reporting form address and QR code. - [Download the case handler manual](https://ethicsportal.eu/developers/api/operations/downloadcasehandlermanual.md): Manual for the people who handle reports. - [Read billing status](https://ethicsportal.eu/developers/api/operations/getbillingstatus.md): Access and subscription status, read from EthicsPortal's synced billing records. - [Create a subscription checkout link](https://ethicsportal.eu/developers/api/operations/createcheckoutlink.md): Return a Stripe Checkout link for the monthly or yearly plan. - [Create a billing portal link](https://ethicsportal.eu/developers/api/operations/createbillingportallink.md): Return a Stripe customer portal link where a person changes the plan, updates the payment method, downloads invoices or cancels. - [Send product feedback](https://ethicsportal.eu/developers/api/operations/submitfeedback.md): File a bug report, feature request or other feedback to EthicsPortal, as the in-app feedback form does. - [Receive a webhook event](https://ethicsportal.eu/developers/api/webhooks/receivereportevent.md): EthicsPortal sends a signed POST request to your HTTPS endpoint when a report is created or changes, or when a deadline is close or has passed. ## Examples - [Fetch every report](https://ethicsportal.eu/developers/examples/pagination.md): A Python example that follows signed pagination cursors and only ever requests the report collection. - [Verify a webhook](https://ethicsportal.eu/developers/examples/verify-webhook.md): Verify raw webhook bytes, timestamp tolerance and event IDs with Node.js. ## Optional - [Public developer resources](https://ethicsportal.eu/developers/public-resources.md): Markdown content negotiation, machine-readable documents and public discovery resources. - [Integration changelog](https://ethicsportal.eu/developers/changelog.md): How the EthicsPortal API and webhook contract changes, what your client must tolerate, and every change so far.