1. API Reference
  3. Get started
  5. Authentication
Website
  • API overview
  • API quickstart
  • Authentication
  • Project scoping
  • Requests and responses
  • Pagination and filtering
  • Errors
  • GETList supported database engines
  • POSTList projects
  • POSTCreate a project
  • GETGet a project
  • DELETEDelete a project
  • PATCHUpdate a project
  • POSTCreate a source
  • POSTList sources
  • GETGet source details
  • DELETEDelete a source
  • PATCHUpdate a source
  • POSTCreate secret metadata
  • POSTList secret metadata
  • GETGet secret metadata
  • DELETEDelete secret metadata
  • PATCHUpdate secret metadata
  • POSTCreate a schedule
  • POSTList schedules
  • POSTSummarize schedule statuses
  • GETGet a schedule
  • DELETEDelete a schedule
  • PATCHUpdate a schedule
  • DELETERemove a schedule gate
  • POSTActivate or pause a schedule
  • POSTQueue a manual check
  • POSTCreate an immutable report
  • POSTList reports
  • GETGet report details
  • DELETEDelete a report
  • POSTDownload a report
  • POSTGet the API-key scope catalog
  • POSTCreate an API key
  • POSTList API-key metadata
  • GETGet API-key metadata
  • DELETEDelete an API key
  • PATCHUpdate API-key metadata
  • POSTCreate a notification channel
  • POSTList notification channels
  • POSTResolve notification channels by ID
  • GETGet notification channel details
  • DELETEDelete a notification channel
  • PATCHUpdate a notification channel
  • POSTSend a test notification
  • POSTCreate a project worker
  • POSTList project workers
  • GETGet worker details
  • DELETEDelete a worker
  • PATCHUpdate a worker
  • POSTRead live worker agent logs
  • POSTList checks
  • POSTSummarize check statuses
  • GETGet check details
  • POSTGet check log sections
  • POSTDownload a check log
  • POSTDownload check audit evidence
  • POSTList notification messages
  • GETGet notification message details

Authentication

Create, store, scope, rotate, and send RestoreTrust project API keys safely.

Loading documentation…

API quickstart< PreviousProject scopingNext >

Powered by heyo

On this page

Create and rotate keysScope catalogAuthentication failures

API keys are the supported credential for customer automation. Each key is bound to one project and carries an explicit set of scopes.

bash
curl --request POST \  --url "https://api.restoretrust.example/v1/checks/list" \  --header "Content-Type: application/json" \  --header "X-API-Key: rtk_REPLACE_WITH_YOUR_KEY" \  --data '{    "project_id": "65f0c7a9a7d6b4e2c1234567",    "pagination": { "limit": 25 }  }'
Treat API keys as secrets

Send keys only in the X-API-Key header over HTTPS. Do not put them in query strings, logs, screenshots, source code, or client-side applications.

Create and rotate keys

API-key creation requires an interactive RestoreTrust console session; an API key cannot mint another key. The create response shows the plaintext secret exactly once.

  1. Create a replacement key with only the scopes the integration needs.
  2. Store the returned secret in your secret manager.
  3. Update the integration and verify requests with the replacement.
  4. Pause or delete the old key.

See Create API key for the session-only request contract and API keys for lifecycle behavior.

Scope catalog

Scopes have the form v1.<resource>:<action>. The supported API-key scopes are:

ResourceScopes
Checksv1.checks:read
Sourcesv1.sources:read, v1.sources:write, v1.sources:delete
Secretsv1.secrets:read, v1.secrets:write, v1.secrets:delete
Schedulesv1.schedules:read, v1.schedules:write, v1.schedules:delete
Reportsv1.reports:read, v1.reports:write, v1.reports:delete
Notification channelsv1.notification-channels:read, v1.notification-channels:write, v1.notification-channels:delete
Messagesv1.messages:read
Workersv1.workers:read, v1.workers:write, v1.workers:delete
API-key metadatav1.api-keys:read, v1.api-keys:write, v1.api-keys:delete

You can also fetch the current catalog with Get API-key scope catalog. A calling API key needs v1.api-keys:read.

Write does not imply delete

Read, write, and delete are independent. Grant every required scope explicitly. v1.api-keys:write updates existing key metadata only; it does not authorize key creation.

Authentication failures

The API returns 401 when a key is missing, invalid, paused, expired, or lacks the operation's required scope. A key expires after its expires_on UTC date has passed.

Interactive console session cookies and CSRF tokens are managed by the console. They are not a replacement authentication method for unattended integrations.

Related topics

  • Understand project binding
  • Manage API-key metadata
  • Handle authentication errors