Skip to content

Credential Vault ​

In the dashboard, this vault lives under Connections → Credentials.

Most sources don't take a raw secret inline. Instead they reference a secret stored in the named credential vault by its id. You create the credential once, then point one or more sources at it. The secret is not written into the source config, and the API does not return it again.

The vault is org-scoped and admin-only: every endpoint requires an org admin. Credentials are shared between the sensors that ingest and the Workers that act — anything consuming the same secret shape reuses one credential (a GitHub PAT, for example, is one github_token credential whether a GitHub sensor reads with it or a GitHub-issue Worker writes with it).

Credential types ​

Each credential has a type that declares its shape. The types a source can reference:

TypeUsed bySecret shape
github_tokenGitHub sourceGitHub PAT with read access to the org/repos
slack_bot_tokenSlack sensor; slack_bot Worker delivery channel (UI label Slack Bot); @corveil chatBot token, xoxb-… (chat:write / reactions:write to deliver and ACK). On the official Corveil Slack app, Add to Slack creates this credential; the admin does not paste the token.
slack_signing_secretBring-your-own Slack app only (slack_byo_app on, or Slack OAuth unset). Events API at /webhooks/slack/{token}. The official Corveil Slack app does not ask for this; events are verified with the deployment secret.Signing Secret from the Slack app Basic Information page — not the bot token
google_service_account_jsonGoogle Meet, Google Calendar, Google Drive, Gmail, Google Chat sourcesFull service-account key JSON
jira_api_tokenJira and Confluence Cloud sourcesAtlassian Cloud API token
linear_api_keyLinear sourceLinear personal API key (lin_api_…)
asana_patAsana sourceAsana personal access token (opaque; often 1/{gid}:{secret})
monday_api_tokenMonday.com sourceMonday.com personal API token
notion_tokenNotion sourceNotion internal integration token (ntn_… or legacy secret_…)
airtable_patAirtable sourceAirtable personal access token (pat…). Not a retired API key or an OAuth access token.
figma_access_tokenFigma sourceFigma personal access token (figd_…, sent as X-Figma-Token) or OAuth access token (sent as Bearer). Team, folder, and file IDs are sensor config.
zoom_s2s_oauthZoom Transcripts sourceZoom Server-to-Server OAuth JSON: {"account_id","client_id","client_secret"}
atlassian_dc_patJira Data Center and Confluence Data Center sourcesData Center personal access token (opaque; no ATATT prefix)
shellcrm_api_keyshell-crm sourceshell-crm API key (client_id:client_secret)
microsoft_graphMicrosoft Teams, SharePoint / OneDrive, Outlook Calendar, Outlook (email), and Microsoft Entra ID sourcesEntra ID app registration as JSON: {"tenant_id","client_id","client_secret"}
microsoft_graph_delegatedOneNote sourceDelegated sign-in as JSON: {"tenant_id","client_id","client_secret"?,"refresh_token"}. The refresh token rotates on every use and Corveil writes the new one back.
gitlab_tokenGitLab sourceGitLab personal / group / project access token (glpat-…); read_api
bitbucket_access_tokenBitbucket sourceBitbucket Cloud access token (preferred), app password, or Atlassian API token
hubspot_access_tokenHubSpot sourceHubSpot private-app token or account Service Key (pat-…)
intercom_access_tokenIntercom sourceIntercom private-app access token (Authorization: Bearer). Not an OAuth marketplace token.
zoominfo_pkiZoomInfo sourceZoomInfo Enterprise API client for PKI authentication, as JSON: {"username", "client_id", "private_key"} (PEM RSA key from the ZoomInfo Admin Portal). The sensor signs a short client JWT with the key; a password is refused.
salesforce_connected_appSalesforce sourceConnected App JSON: {"login_url","client_id","client_secret"}
greenhouse_harvest_api_keyGreenhouse sourceGreenhouse Harvest API key (HTTP Basic username, empty password). Not a Job Board token.
lever_api_keyLever sourceLever API key (HTTP Basic username, empty password). Not an OAuth partner token.
workday_api_clientWorkday sourceWorkday API Client JSON: {"host","tenant","client_id","client_secret","refresh_token"}
pagerduty_api_keyPagerDuty sourcePagerDuty REST API key (Authorization: Token token=…). Not an OAuth access token.
azure_devops_credentialsAzure DevOps sourceJSON with exactly one form: {"pat"} (personal access token, Services or Server) or {"tenant_id","client_id","client_secret"} (Entra ID service principal, Services only). The organization URL is sensor config.
servicenow_credentialsServiceNow sourceJSON with exactly one pair: {"username","password"} (Basic, integration user) or {"client_id","client_secret"} (OAuth client credentials). The instance URL is sensor config.
zendesk_api_tokenZendesk sourceZendesk API token (HTTP Basic username {email}/token). Agent email and subdomain are sensor config, not this secret.
bamboohr_api_keyBambooHR sourceBambooHR API key (HTTP Basic username, password x). Company subdomain is sensor config, not this secret.
rippling_api_tokenRippling sourceRippling REST API token (Authorization: Bearer). Not an OAuth app-install token.
gusto_api_clientGusto sourceGusto App Integrations OAuth JSON: {"client_id","client_secret","refresh_token","redirect_uri","environment"?}. Refresh tokens are single-use; Corveil rotates the vault row after mint.
okta_service_appOkta sourceOkta API Services app JSON: {"client_id","private_key","key_id"?}. private_key is the app's PEM RSA private key (private-key JWT client auth); no client secret. Scopes okta.users.read + okta.groups.read.
okta_api_tokenOkta sourceOkta SSWS API token (Authorization: SSWS), created by a Read-Only Administrator. Use this or okta_service_app. Org URL is sensor config, not this secret.
gong_access_keyGong sourceJSON {"access_key","access_key_secret"} from Gong Company Settings → API
otter_api_keyOtter.ai sourceOtter Public API key (Authorization: Bearer), Enterprise workspaces only. From otter.ai → Integrations → Developer → Create key. Acts as its user.
fireflies_api_keyFireflies sourceFireflies.ai API key (Authorization: Bearer), one per user. From app.fireflies.ai → Settings → Developer settings. Reads the meetings that user can see.
granola_api_keyGranola sourceGranola public-API key (grn_…, Authorization: Bearer), personal or workspace. From the Granola desktop app → Settings → Connectors → API keys.
box_client_credentialsBox sourceBox Platform app (Server Authentication, Client Credentials Grant) as JSON: {"client_id","client_secret","enterprise_id"}. Not a JWT config.json or a developer token.
dropbox_team_oauthDropbox sourceTeam-scoped Dropbox app as JSON: {"app_key","app_secret","refresh_token"}. The refresh token comes from a team admin authorizing the app with token_access_type=offline; a short-lived sl.… access token is refused.
lucid_credentialsLucid sourceLucid credential as JSON, one of two forms: {"api_key"} (a Lucid API key with the DocumentReadonly grant) or {"client_id","client_secret","refresh_token"} (an OAuth 2.0 user token granted with offline_access). Refresh tokens are single-use; Corveil rotates the vault row after each refresh. Reads what that one Lucid user can see.
aws_access_keyAmazon S3 sourceJSON {"access_key_id","secret_access_key","session_token"?}. Required on Corveil Cloud. A self-hosted deployment can allow a blank credential (the AWS default chain) with CORVEIL_SENSOR_AMBIENT_CREDENTIALS=true; see Amazon S3.

Other types (slack_webhook, generic_webhook) exist for Worker delivery channels and are not referenced by sensors. The Jenkins and Webhook sources use no vault credential — their webhook tokens are generated server-side at create time.

The live list for your instance:

bash
curl -sS https://your-corveil-host/api/credentials/types \
  -H "Authorization: Bearer <admin-session-or-key>"

Returns each registered type with its human-readable display name.

Create a credential ​

POST /api/credentials

json
{
  "type": "github_token",
  "name": "acme-readonly-pat",
  "secret": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
bash
curl -sS -X POST https://your-corveil-host/api/credentials \
  -H "Authorization: Bearer <admin-session-or-key>" \
  -H "Content-Type: application/json" \
  -d '{"type":"github_token","name":"acme-readonly-pat","secret":"ghp_..."}'

The response echoes the stored credential's metadata — including its id — but never the secret. The secret is validated at write time for the given type, so a malformed value is rejected with a 400 before it lands in the vault.

Copy the returned id; that's what you put in a source's credentials block.

List, read, update, delete ​

Method & pathPurpose
GET /api/credentialsList all credentials (metadata only). Add ?type=github_token to filter.
GET /api/credentials/{id}Fetch one credential's metadata.
PATCH /api/credentials/{id}Rename ({"name": "..."}) or rotate the secret ({"secret": "..."}).
DELETE /api/credentials/{id}Remove a credential.

How a source references a credential ​

When you create a source, the credentials block holds the credential id (a UUID), not the secret:

json
{
  "sensor_type": "github",
  "name": "Acme GitHub",
  "config": { "org": "acme" },
  "credentials": { "token": "6f1c2b8e-0a4d-4d6a-9f2e-1c3b5a7d9e11" }
}

The token key is the credential field the GitHub source declares; its value is the id returned by POST /api/credentials. Every source guide in this section lists exactly which credential type its credential field expects.

The Add sensor UI renders a dropdown of matching credentials for each credential field, so you rarely assemble this JSON by hand — but the same shape is what the API expects for programmatic setup.