Connections

A connection is a stored credential that allows agents and skills in your workspace to authenticate with an external service. ProvenanceOne supports 12 integrations across two auth types: OAuth 2.0 and API key / service account. Credential values are stored in the secrets vault and are never returned in API responses.

---

When to use

Create a connection when a workflow step needs to interact with an external service — for example, posting a message to Slack, querying a GitHub repository, creating a Jira ticket, or pulling metrics from Datadog. Without a valid connection, skills that require authentication to that service will fail at runtime.

---

Key concepts

Connection status — every connection has one of three statuses:

• active — credentials are valid and the connection is ready to use
• paused — the connection has been manually suspended; it will not be used in runs until re-enabled
• error — credential validation has failed (e.g. an OAuth token has expired and could not be refreshed, or an API key was revoked)

OAuth 2.0 flow — the user is redirected to the external provider to grant access. The resulting refresh token is stored in platform database; access tokens are retrieved from the provider and auto-refreshed by a per-provider rotation service. Access tokens are not stored long-term.

API key / service account connections — the API key or service account credential is stored directly in the secrets vault. Rotation is manual.

Credentials are write-only — once saved, credential values cannot be read back from the API. This applies to both OAuth tokens and API keys.

---

Supported integrations

Before creating a connection, you need a valid credential from the provider — an OAuth app (for OAuth 2.0 integrations) or an API key / service account (for the others). The links below go directly to each provider's credential setup documentation.

Integration	Auth type	Provider credential docs
Slack	OAuth 2.0	Create a Slack app and configure OAuth
GitHub	OAuth 2.0	Register a GitHub OAuth App
LinkedIn	OAuth 2.0	LinkedIn OAuth 2.0 authorization code flow
X / Twitter	OAuth 2.0	X OAuth 2.0 setup
Okta	SAML / OAuth 2.0	Okta OAuth 2.0 and OIDC concepts
Jira	API Key	Create and manage Atlassian API tokens
ServiceNow	Service Account	ServiceNow REST API authentication
Snyk	API Key	Snyk API authentication
PagerDuty	API Key	Create a PagerDuty API access key
Datadog	API Key	Datadog API and application keys
Zendesk	API Key	Generate a Zendesk API token
Snowflake	Service Account	Snowflake user management

---

How it works

Creating an OAuth 2.0 connection

1. Go to Connections → New Connection and select the provider (e.g. Slack).
2. Click Authorize. You are redirected to the provider's OAuth consent screen.
3. Grant the requested permissions. The provider redirects back to ProvenanceOne with an authorization code.
4. ProvenanceOne exchanges the code for a refresh token and stores it in platform database. An initial access token is fetched.
5. The connection status becomes active.
6. A rotation service runs on a per-provider schedule to refresh the access token before it expires. If refresh fails, the status transitions to error.

Creating an API key connection

1. Go to Connections → New Connection and select the provider (e.g. Datadog).
2. Enter the API key or service account credentials in the form.
3. Click Save. The credential is written to the secrets vault.
4. Optionally, click Test connection (or call POST /connections/{id}/test) to validate the credential against the live provider API.
5. The connection status becomes active.

Re-authorizing a connection in error status

1. Open the connection in the Connections list.
2. Click Re-authorize (OAuth) or Update credentials (API key).
3. For OAuth: complete the consent flow again. A new refresh token is stored and the status reverts to active.
4. For API key: paste the new credential value. The old value in the secrets vault is overwritten.

Removing a connection

Call DELETE /connections/{id} or click Delete in the UI. Any workflow step that references the deleted connection will fail at runtime. Check workflow configurations before deleting.

Warning: Deleting a connection does not remove references to it in workflow steps. Update or remove those steps before deleting the connection.

---

Configuration options

Field	Type	Required	Default	Description
name	string	Yes	—	Display name for the connection
provider	enum	Yes	—	One of the 12 supported provider identifiers
authType	enum	Yes	—	oauth2 or apikey or serviceaccount
credential	string	Yes (API key)	—	API key or service account credential; write-only
status	enum	—	active	active | paused | error; managed by platform

---

Examples

Test a connection via API

curl -X POST https://api.provenanceone.ai/connections/{id}/test \
  -H "Authorization: Bearer YOUR_JWT"

Returns 200 if the credential validates successfully against the live provider, or a 4xx with an error message if not.

List all connections

curl https://api.provenanceone.ai/connections \
  -H "x-api-key: YOUR_KEY"

The response includes id, name, provider, status, and timestamps but never the credential value.

Pause a connection

curl -X PATCH https://api.provenanceone.ai/connections/{id} \
  -H "Authorization: Bearer YOUR_JWT" \
  -d '{"status": "paused"}'

---

Common mistakes

• Not testing after creating an API key connection. OAuth connections are validated during the consent flow, but API key connections are saved without validation unless you explicitly call POST /connections/{id}/test. Always test before using a connection in a production workflow.
• Granting minimal OAuth scopes and then expecting full functionality. The permissions granted during the OAuth consent flow determine what the connection can do. If a skill fails with a permission error, the OAuth scopes granted at authorization time may be insufficient. Re-authorize the connection and grant the required scopes.
• Sharing a single connection across unrelated workflows. If one workflow's activity causes a rate limit or a revocation, all workflows using that connection are affected. For high-volume or critical workflows, consider separate connections.
• Deleting a connection without updating workflow steps. See the warning above.

---

Troubleshooting

Connection status is error after a period of active — for OAuth connections, this typically means the refresh token has expired or been revoked. Click Re-authorize and complete the OAuth flow again. For API key connections, verify the key has not been rotated or revoked in the external service.

POST /connections/{id}/test returns 401 from the provider — the stored credential is invalid. For OAuth, re-authorize. For API key, update the credential value.

OAuth re-authorization redirects back but status stays error — check that the OAuth redirect URI https://app.provenanceone.ai/auth/callback is registered in the external service's allowed redirect URIs. A mismatch will cause the exchange to fail silently.

Snowflake or ServiceNow connection fails after rotation — service account credentials for these providers must be updated manually. Call PATCH /connections/{id} with the new credential value, then call POST /connections/{id}/test to confirm.

A workflow run fails with connection not found — the connection ID referenced in the workflow step no longer exists (deleted or from a different workspace). Update the step configuration to reference a valid connection.

---

Security and permissions

Operation	admin	editor	viewer
Create connection	Yes	Yes	No
Edit / re-authorize connection	Yes	Yes	No
Delete connection	Yes	Yes	No
View connection list and status	Yes	Yes	Yes
Test connection	Yes	Yes	No

Connection credentials are stored in the secrets vault and are never returned in GET or list API responses. Access to connection details is audited: connection.accessed is a high-risk event. connection.updated is emitted for any credential or configuration change.

Note: The connection.accessed audit event (risk: high) is emitted when a connection's detail record is read by a user. This is distinct from the connection being used in a run, which is recorded at the run-step level.

For the full security model, see /docs/security.

---

Related pages

• Security Model
• Data — Datastores and Secrets
• Audit Log
• Settings

---

FAQ